universal-parcel-scraper 0.70.3-main.907 → 0.72.0-main.916

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 **120 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **125 dedicated adapters** and **5 universal fallbacks**
 
 <sub>207 catalog entries · 66 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 3,350 such statuses, each filed under one stage.
+The carrier folders record 3,501 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

@@ -4822,7 +4822,8 @@
     "timezone": "Europe/Athens",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "box-now",
+      "recognitionRank": 48
     },
     "canaryUrl": "https://boxnow.cy/track",
     "trackingSearchUrl": "https://boxnow.cy/track",
@@ -6068,7 +6069,9 @@
     "timezone": "Europe/Bucharest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "fan-courier",
+      "recognitionRank": 51,
+      "localClocks": true
     },
     "canaryUrl": "https://www.fancourier.ro/awb-tracking/",
     "trackingUrlTemplate": "https://www.fancourier.ro/awb-tracking/?tracking={trackingNumber}",
@@ -6108,7 +6111,9 @@
     "timezone": "Europe/Budapest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "foxpost",
+      "recognitionRank": 52,
+      "localClocks": true
     },
     "canaryUrl": "https://foxpost.hu/csomagkovetes/",
     "trackingUrlTemplate": "https://foxpost.hu/csomagkovetes/?code={trackingNumber}",
@@ -7215,7 +7220,8 @@
     "timezone": "Europe/Warsaw",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "orlen-paczka",
+      "recognitionRank": 49
     },
     "canaryUrl": "https://www.orlenpaczka.pl/sledz-paczke/",
     "trackingUrlTemplate": "https://www.orlenpaczka.pl/sledz-paczke/?numer={trackingNumber}",
@@ -7646,9 +7652,11 @@
     "timezone": "Europe/Bucharest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "sameday",
+      "recognitionRank": 53
     },
     "canaryUrl": "https://sameday.ro/",
+    "trackingSearchUrl": "https://sameday.ro/",
     "linkRules": [],
     "detectionRules": [
       {

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 207,
-  "activeAdapters": 120,
+  "activeAdapters": 125,
   "countries": 66,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -8410,6 +8410,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8418,6 +8421,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8426,6 +8432,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8434,6 +8443,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8442,6 +8454,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8450,6 +8465,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8458,6 +8476,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8466,6 +8487,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8474,6 +8498,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8482,6 +8509,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -10022,6 +10052,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]
@@ -10039,6 +10070,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]
@@ -10056,6 +10088,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]
@@ -10074,6 +10107,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "ukrposhta",
       "la-poste",
       "delhivery"
@@ -10093,6 +10127,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "ukrposhta",
       "la-poste",
       "delhivery"
@@ -10112,6 +10147,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "ukrposhta",
       "la-poste",
       "delhivery"
@@ -10130,6 +10166,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]
@@ -10148,6 +10185,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "ukrposhta",
       "la-poste",
       "delhivery"
@@ -10166,6 +10204,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]
@@ -10191,6 +10230,7 @@
       "orlen-paczka"
     ],
     "asked": [
+      "orlen-paczka",
       "la-poste",
       "delhivery"
     ]

package/dist/browser/scraper.js

@@ -3953,7 +3953,8 @@ var ye = {
 		timezone: "Europe/Athens",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "box-now",
+			recognitionRank: 48
 		},
 		canaryUrl: "https://boxnow.cy/track",
 		trackingSearchUrl: "https://boxnow.cy/track",
@@ -4877,7 +4878,9 @@ var ye = {
 		timezone: "Europe/Bucharest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "fan-courier",
+			recognitionRank: 51,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.fancourier.ro/awb-tracking/",
 		trackingUrlTemplate: "https://www.fancourier.ro/awb-tracking/?tracking={trackingNumber}",
@@ -4905,7 +4908,9 @@ var ye = {
 		timezone: "Europe/Budapest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "foxpost",
+			recognitionRank: 52,
+			localClocks: !0
 		},
 		canaryUrl: "https://foxpost.hu/csomagkovetes/",
 		trackingUrlTemplate: "https://foxpost.hu/csomagkovetes/?code={trackingNumber}",
@@ -5730,7 +5735,8 @@ var ye = {
 		timezone: "Europe/Warsaw",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "orlen-paczka",
+			recognitionRank: 49
 		},
 		canaryUrl: "https://www.orlenpaczka.pl/sledz-paczke/",
 		trackingUrlTemplate: "https://www.orlenpaczka.pl/sledz-paczke/?numer={trackingNumber}",
@@ -6056,9 +6062,11 @@ var ye = {
 		timezone: "Europe/Bucharest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "sameday",
+			recognitionRank: 53
 		},
 		canaryUrl: "https://sameday.ro/",
+		trackingSearchUrl: "https://sameday.ro/",
 		linkRules: [],
 		detectionRules: [{
 			pattern: "^1[A-Z]{3,5}\\d{9,11}$",
@@ -11660,6 +11668,7 @@ var _c = {
 	aliexpress: 14,
 	"australia-post": 6,
 	"austrian-post": 39,
+	"box-now": 48,
 	bpost: 37,
 	brt: 42,
 	"canada-post": 15,
@@ -11680,7 +11689,9 @@ var _c = {
 	"dpd-de": 65,
 	"dpd-pl": 8,
 	emile: 4,
+	"fan-courier": 51,
 	"four-px": 13,
+	foxpost: 52,
 	"gls-ch": 50,
 	"gls-de": 60,
 	"gls-fr": 61,
@@ -11696,6 +11707,7 @@ var _c = {
 	"nz-post": 32,
 	omgo: 1,
 	ontrac: 21,
+	"orlen-paczka": 49,
 	"poczta-polska": 31,
 	"poste-italiane": 46,
 	posti: 27,
@@ -11703,6 +11715,7 @@ var _c = {
 	postnord: 7,
 	purolator: 12,
 	"relais-colis": 25,
+	sameday: 53,
 	seur: 43,
 	sto: 10,
 	"swiss-post-cargo": 11,

package/dist/carriers/box-now/adapter.d.ts

@@ -0,0 +1,13 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare const BOX_NOW_ENDPOINT = "https://api-production.boxnow.cy/api/v1/parcels:track";
+export declare class BoxNowTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/box-now/adapter.js

@@ -0,0 +1,51 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
+import { BOX_NOW_MAX_BYTES, normalizeBoxNowNumber, parseBoxNow, PROVIDER } from './parser.js';
+// The tracker on boxnow.cy posts here. The Greek, Bulgarian and Croatian sites
+// post to their own hosts, which answer the same parcels.
+export const BOX_NOW_ENDPOINT = 'https://api-production.boxnow.cy/api/v1/parcels:track';
+export class BoxNowTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeBoxNowNumber(raw);
+        return runSteps({ carrier: 'box-now', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    let bytes;
+                    try {
+                        ({ bytes } = await fetchBounded(BOX_NOW_ENDPOINT, { method: 'POST', signal,
+                            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': userAgentOf(this.options.userAgent) },
+                            body: JSON.stringify({ parcelId: number }) }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: BOX_NOW_MAX_BYTES, fetcher: this.options.fetcher }));
+                    }
+                    catch (error) {
+                        // An unknown parcel is an empty list; a missing route is not a missing parcel.
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                            throw new TransportError(PROVIDER, 'BOX NOW tracking endpoint is unavailable', { cause: error });
+                        }
+                        throw error;
+                    }
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, PROVIDER);
+                    }
+                    catch (cause) {
+                        // The Greek site sits behind Cloudflare's challenge; the API could too.
+                        if (/<title>\s*Just a moment|cf-chl-|challenge-platform|cf-turnstile/i.test(decodeText(bytes.subarray(0, 64_000)))) {
+                            throw new ChallengeError(PROVIDER, 'BOX NOW answered with a browser challenge', { cause });
+                        }
+                        throw new SchemaError(PROVIDER, 'BOX NOW returned invalid tracking JSON', { cause });
+                    }
+                    return parseBoxNow(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new BoxNowTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return { id: 'box-now', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeBoxNowNumber(number))) };
+};

package/dist/carriers/box-now/carrier.json

@@ -20,17 +20,64 @@
   "timezone": "Europe/Athens",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "box-now",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 48
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "eta",
+    "delivered_at",
+    "pickup_point",
+    "destination_country"
+  ],
   "portal": {
     "searchUrl": "https://boxnow.cy/track",
     "canaryUrl": "https://boxnow.cy/track",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "delivered_at",
+      "pickup_point",
+      "pickup_point_address",
+      "pickup_deadline",
+      "coordinates",
+      "sender_name",
+      "payment_details"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code",
+      "eta",
+      "delivered_at",
+      "pickup_point",
+      "destination_country"
+    ],
+    "discarded": [
+      "pickup_point_address",
+      "pickup_deadline",
+      "coordinates",
+      "sender_name",
+      "payment_details",
+      "postcodes",
+      "size_class",
+      "delivery_partner_reference"
+    ],
+    "unavailable": [
+      "weight",
+      "service_name",
+      "proof_of_delivery"
+    ]
   },
   "links": [],
   "detection": []

package/dist/carriers/box-now/parser.d.ts

@@ -0,0 +1,6 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "BOX NOW";
+export declare const BOX_NOW_MAX_BYTES = 256000;
+/** BOX NOW's partner API manual: a parcel id is always ten digits. */
+export declare function normalizeBoxNowNumber(raw: string): string;
+export declare function parseBoxNow(payload: unknown, rawNumber: string): CarrierResult;

package/dist/carriers/box-now/parser.js

@@ -0,0 +1,97 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { lastMovement } from '../../core/result/pickup.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { countryCode, explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { boxNowStatus } from './status.js';
+export const PROVIDER = 'BOX NOW';
+export const BOX_NOW_MAX_BYTES = 256_000;
+/** BOX NOW's partner API manual: a parcel id is always ten digits. */
+export function normalizeBoxNowNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^\d{10}$/.test(number))
+        throw new InvalidInputError(PROVIDER, 'BOX NOW parcel ids are ten digits');
+    return number;
+}
+const code = (value) => {
+    const text = clean(value, 64);
+    return /^[a-z]+(?:-[a-z]+)*$/.test(text) ? text : '';
+};
+// The trackers stop showing the estimate once a parcel waits in its locker or
+// its journey has ended; only a parcel still on its way keeps one.
+const ON_THE_WAY = new Set(['registered', 'accepted', 'in_transit']);
+export function parseBoxNow(payload, rawNumber) {
+    const number = normalizeBoxNowNumber(rawNumber);
+    if (!isRecord(payload) || !Array.isArray(payload.data) || payload.data.length > 10)
+        throw new SchemaError(PROVIDER);
+    // The official tracker reads an empty list as a parcel id that does not exist.
+    if (!payload.data.length)
+        throw new NotFoundError(PROVIDER);
+    const parcel = payload.data[0];
+    if (payload.data.length !== 1 || !isRecord(parcel) || parcel.id !== number) {
+        throw new SchemaError(PROVIDER, 'BOX NOW did not identify one matching parcel');
+    }
+    const state = code(parcel.state);
+    if (!state)
+        throw new SchemaError(PROVIDER, 'BOX NOW returned a parcel without a state');
+    const rows = parcel.events ?? [];
+    if (!Array.isArray(rows) || rows.length > 200)
+        throw new SchemaError(PROVIDER, 'BOX NOW returned an invalid parcel history');
+    const scans = [];
+    const seen = new Set();
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'BOX NOW returned an incomplete scan');
+        const type = code(row.type);
+        const at = explicitOffsetTime(row.createTime);
+        if (!type || !at)
+            throw new SchemaError(PROVIDER, 'BOX NOW returned a scan without a type or clock');
+        const { wording, stage } = boxNowStatus(type);
+        // A new parcel's place is its sender. Postcodes are left out.
+        const location = type === 'new' ? '' : clean(row.locationDisplayName, 160);
+        const event = { time: at.iso, description: wording, provider_code: type,
+            ...(location ? { location } : {}), ...(stage ? { stage, stage_source: 'carrier_map' } : {}) };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            scans.push({ event, at: at.timestamp, type });
+        }
+    }
+    // The reply lists scans oldest first; equal clocks keep their order, reversed.
+    const ordered = scans.map((scan, index) => ({ ...scan, index }))
+        .sort((left, right) => right.at - left.at || right.index - left.index);
+    const events = ordered.map(({ event }) => event);
+    // The trackers show the newest scan's type while the parcel's state only
+    // says it is on its way, and the state otherwise.
+    const newest = ordered[0]?.type;
+    const shown = newest && ['in-transit', 'in-depot'].includes(state)
+        && ['accepted-to-locker', 'accepted-for-return', 'in-depot', 'new', 'wait-for-load'].includes(newest) ? newest : state;
+    const current = boxNowStatus(shown);
+    const stage = current.stage;
+    const delivered = stage === 'delivered' ? events.find(event => event.stage === 'delivered') : undefined;
+    const deliveredIndex = delivered ? events.indexOf(delivered) : -1;
+    // The recipient's locker, by name only, once the parcel waits there or was collected from it.
+    const destination = isRecord(parcel.destination) ? parcel.destination : null;
+    const collected = deliveredIndex >= 0 && lastMovement(events.slice(deliveredIndex + 1)) === 'ready_for_pickup';
+    const locker = destination?.type === 'apm' && (stage === 'ready_for_pickup' || collected) ? clean(destination.name, 160) : '';
+    const country = destination ? countryCode(destination.country) : null;
+    const eta = typeof parcel.etaDate === 'string' && stage && ON_THE_WAY.has(stage) ? explicitOffsetTime(parcel.etaDate) : null;
+    // The trackers print the estimate as a day in Athens.
+    const expected = eta ? DateTime.fromMillis(eta.timestamp, { zone: 'Europe/Athens' }).toISODate() : null;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: 'carrier_map' } : {}),
+        last_status_text: current.wording,
+        ...(events.length ? {} : { provider_code: shown, summary_only: true }),
+        last_update: events[0]?.time ?? null,
+        expected_delivery: expected,
+        ...(delivered?.time ? { delivered_at: delivered.time } : {}),
+        ...(locker ? { pickup_point: locker } : {}),
+        ...(country ? { destination_country: country } : {}),
+        events: events.slice(0, 100),
+        ...(events.length > 100 ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/box-now/status.d.ts

@@ -0,0 +1,11 @@
+import type { Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** One BOX NOW parcel state or event type: the English wording the adapter gives it and its stage. */
+interface BoxNowStatus {
+    readonly wording: string;
+    readonly stage?: Stage;
+}
+/** The wording and stage of one state or event type; a type the map does not know keeps its code as wording. */
+export declare function boxNowStatus(code: string): BoxNowStatus;
+export declare const statusMap: CarrierStatusMap;
+export {};

package/dist/carriers/box-now/status.js

@@ -0,0 +1,36 @@
+// The tracking API names each scan and the parcel's state with one vocabulary.
+// Wordings follow the definitions in BOX NOW's partner API manual, else the
+// English wording of its country sites' trackers. A parcel goes to the locker
+// its recipient chose: final-destination is a parcel waiting there.
+const STATUSES = new Map([
+    ['new', { wording: 'Parcel has been registered in the system', stage: 'registered' }],
+    ['accepted-to-locker', { wording: 'The parcel has been placed in the locker', stage: 'accepted' }],
+    ['accepted-in-locker', { wording: 'The parcel has been placed in the locker', stage: 'accepted' }],
+    ['in-transit', { wording: 'Parcel is being transferred to a specific location', stage: 'in_transit' }],
+    ['in-depot', { wording: 'Parcel is in one of our warehouses', stage: 'in_transit' }],
+    // Waiting in a locker for a courier, after a drop-off or an expired pickup.
+    ['wait-for-load', { wording: 'Parcel is waiting in a specific APM to be taken over by BOX NOW courier', stage: 'in_transit' }],
+    ['final-destination', { wording: 'Parcel has reached its final destination, waiting for pickup', stage: 'ready_for_pickup' }],
+    ['in-final-destination', { wording: 'Parcel has reached its final destination, waiting for pickup', stage: 'ready_for_pickup' }],
+    ['delivered', { wording: 'Parcel has been delivered', stage: 'delivered' }],
+    ['returned', { wording: 'Parcel has been returned to the sender', stage: 'returned' }],
+    ['expired', { wording: 'Expired', stage: 'exception' }],
+    ['expired-return', { wording: 'Delivery has expired', stage: 'exception' }],
+    ['missing', { wording: 'Parcel search - We will update you shortly', stage: 'exception' }],
+    ['lost', { wording: 'Lost', stage: 'exception' }],
+    ['canceled', { wording: 'Parcel order had been cancelled by the sender', stage: 'exception' }],
+    ['cancelled', { wording: 'Parcel order had been cancelled by the sender', stage: 'exception' }],
+    ['cancelled-return', { wording: 'Return of parcel, cancelled by sender', stage: 'exception' }],
+    ['accepted-for-return', { wording: 'The parcel has been placed in the locker' }],
+]);
+/** The wording and stage of one state or event type; a type the map does not know keeps its code as wording. */
+export function boxNowStatus(code) {
+    return STATUSES.get(code) ?? { wording: code };
+}
+export const statusMap = {
+    stage: (code) => (code ? STATUSES.get(code)?.stage : undefined),
+    gaps: [{
+            code: 'accepted-for-return',
+            note: 'A parcel put back into a locker to go back. The trackers word it like a sender drop-off, and no reply showed whether it ends the delivery or starts a return to the sender.',
+        }],
+};

package/dist/carriers/box-now/statuses.json

@@ -1,4 +1,23 @@
 {
   "carrier": "box-now",
-  "entries": []
+  "entries": [
+    { "code": "new", "wording": "Parcel has been registered in the system", "language": "en", "stage": "registered", "confirmedBy": "live", "note": "The API sends the code only; the wording is the partner API manual's definition. Its place is the sender, which the adapter drops." },
+    { "code": "accepted-to-locker", "wording": "The parcel has been placed in the locker", "language": "en", "stage": "accepted", "confirmedBy": "live", "note": "The sender's drop-off at a locker or BOX NOW store; the wording is the Cypriot tracker's English one." },
+    { "code": "accepted-in-locker", "wording": "The parcel has been placed in the locker", "language": "en", "stage": "accepted", "confirmedBy": "bundle", "note": "The Bulgarian tracker shows it like accepted-to-locker." },
+    { "code": "in-transit", "wording": "Parcel is being transferred to a specific location", "language": "en", "stage": "in_transit", "confirmedBy": "live", "note": "Seen as a parcel's state; the trackers then show the newest scan's type." },
+    { "code": "in-depot", "wording": "Parcel is in one of our warehouses", "language": "en", "stage": "in_transit", "confirmedBy": "live", "note": "Its place names the hub or depot." },
+    { "code": "wait-for-load", "wording": "Parcel is waiting in a specific APM to be taken over by BOX NOW courier", "language": "en", "stage": "in_transit", "confirmedBy": "official-doc", "note": "The manual adds that the courier takes it back to the sender or on to another locker." },
+    { "code": "final-destination", "wording": "Parcel has reached its final destination, waiting for pickup", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "note": "Its place names the recipient's locker." },
+    { "code": "in-final-destination", "wording": "Parcel has reached its final destination, waiting for pickup", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "note": "The state of a parcel whose newest scan is final-destination." },
+    { "code": "delivered", "wording": "Parcel has been delivered", "language": "en", "stage": "delivered", "confirmedBy": "live", "note": "The recipient took the parcel out of the locker; the scan has no place." },
+    { "code": "returned", "wording": "Parcel has been returned to the sender", "language": "en", "stage": "returned", "confirmedBy": "official-doc" },
+    { "code": "expired", "wording": "Expired", "language": "en", "stage": "exception", "confirmedBy": "bundle", "note": "The trackers show it in red with the other ended states." },
+    { "code": "expired-return", "wording": "Delivery has expired", "language": "en", "stage": "exception", "confirmedBy": "official-doc", "note": "Listed among the manual's states; the wording is the trackers' English one." },
+    { "code": "missing", "wording": "Parcel search - We will update you shortly", "language": "en", "stage": "exception", "confirmedBy": "official-doc", "note": "A webhook event in the manual; the wording is the Cypriot tracker's English one." },
+    { "code": "lost", "wording": "Lost", "language": "en", "stage": "exception", "confirmedBy": "official-doc", "note": "Listed among the manual's states; the wording is the Bulgarian and Croatian trackers' English one." },
+    { "code": "canceled", "wording": "Parcel order had been cancelled by the sender", "language": "en", "stage": "exception", "confirmedBy": "official-doc", "note": "The manual lists both spellings." },
+    { "code": "cancelled", "wording": "Parcel order had been cancelled by the sender", "language": "en", "stage": "exception", "confirmedBy": "official-doc" },
+    { "code": "cancelled-return", "wording": "Return of parcel, cancelled by sender", "language": "en", "stage": "exception", "confirmedBy": "official-doc" },
+    { "code": "accepted-for-return", "wording": "The parcel has been placed in the locker", "language": "en", "confirmedBy": "bundle", "note": "Left without a stage: the trackers show it like a sender drop-off, and no reply showed whether it ends the delivery or starts a return to the sender." }
+  ]
 }