universal-parcel-scraper 0.3.4-main.317 → 0.4.0-main.319

package/README.md

@@ -149,7 +149,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 1,673 such statuses, each filed under one stage.
+The carrier folders record 1,675 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/dist/carriers/postlogistics/adapter.js

@@ -25,7 +25,7 @@ import { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/
 import { isRecord } from '../../core/types.js';
 import { referenceConsignment } from '../swiss-post-cargo/reference.js';
 import { postlogisticsIdentifier } from './number.js';
-import { POSTLOGISTICS_IMAGE_CODE, postlogisticsStatus } from './status.js';
+import { POSTLOGISTICS_IMAGE_CODE, postlogisticsStage, postlogisticsStatus } from './status.js';
 const PROVIDER = 'PostLogistics';
 const UPSTREAM = 'PostLogistics tracking';
 const TRACK_URL = 'https://eosapi.postlogistics.ch/api/trackandtrace/public?culture=fr-FR';
@@ -108,6 +108,7 @@ export function parsePostlogisticsTrackingResponse(value, trackingNumber, now =
         time: text(event.TimeStamp),
         location: text(event.City),
         description: text(event.Description),
+        stage: postlogisticsStage(text(event.Status)),
     }));
     const latest = orderedHistory[0]?.event ?? {};
     const latestStatus = text(latest.Status);
@@ -116,6 +117,7 @@ export function parsePostlogisticsTrackingResponse(value, trackingNumber, now =
         .find(Boolean) ?? '';
     return {
         status: postlogisticsStatus(latestStatus),
+        current_stage: postlogisticsStage(latestStatus),
         last_status_text: text(latest.Description) || latestStatus,
         last_update: text(latest.TimeStamp) || null,
         expected_delivery: eta ? eta.slice(0, 10) : null,

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

@@ -2,21 +2,19 @@
  * PostLogistics status vocabulary.
  *
  * Every history entry carries a three-letter `Status` code next to its
- * free-text `Description`. Only the codes that decide the shipment's outcome
- * are mapped; everything else stays `in_transit` and the description is left
- * for the sync's wording classifier. The map is deliberately small: a wrong
- * "delivered" is worse than a missing nuance.
- *
- * The adapter classifies the shipment, not each event: the endpoint gives one
- * code per scan but no stage vocabulary, so events are returned without an
- * explicit stage and the sync records them for review.
+ * free-text `Description`. Confirmed codes classify each scan and the newest
+ * scan's summary. Unknown codes leave the stage to the wording classifier.
+ * An announcement must not become movement when its wording is unrecognized.
  */
 import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
 /** Codes that mean the parcel reached its recipient. */
 export declare const POSTLOGISTICS_DELIVERED_CODES: readonly ["DEL", "DLV", "POD", "SIG"];
 /** The code that means the shipment is announced but not yet moving. */
 export declare const POSTLOGISTICS_NOTIFIED_CODE = "NTF";
 /** The code of an entry that records a picture, not a movement. */
 export declare const POSTLOGISTICS_IMAGE_CODE = "IMG";
+/** The milestone of a scan whose code has a confirmed meaning. */
+export declare function postlogisticsStage(code: string): Stage | undefined;
 /** The shipment status the newest history code implies. */
 export declare function postlogisticsStatus(code: string): CarrierStatus;

package/dist/carriers/postlogistics/status.js

@@ -4,11 +4,24 @@ export const POSTLOGISTICS_DELIVERED_CODES = ['DEL', 'DLV', 'POD', 'SIG'];
 export const POSTLOGISTICS_NOTIFIED_CODE = 'NTF';
 /** The code of an entry that records a picture, not a movement. */
 export const POSTLOGISTICS_IMAGE_CODE = 'IMG';
-/** The shipment status the newest history code implies. */
-export function postlogisticsStatus(code) {
+/** The milestone of a scan whose code has a confirmed meaning. */
+export function postlogisticsStage(code) {
     if (POSTLOGISTICS_DELIVERED_CODES.includes(code))
         return 'delivered';
     if (code === POSTLOGISTICS_NOTIFIED_CODE)
+        return 'registered';
+    if (code === 'RFS')
+        return 'accepted';
+    if (code === 'SCA')
+        return 'out_for_delivery';
+    return undefined;
+}
+/** The shipment status the newest history code implies. */
+export function postlogisticsStatus(code) {
+    const stage = postlogisticsStage(code);
+    if (stage === 'delivered' || stage === 'out_for_delivery')
+        return stage;
+    if (stage === 'registered')
         return 'pending';
     return 'in_transit';
 }

package/dist/carriers/postlogistics/statuses.json

@@ -34,7 +34,21 @@
       "stage": "registered",
       "confirmedBy": "fixture",
       "firstSeen": "2026-09-12",
-      "note": "Shipment announced. The adapter reports the shipment as pending and stamps no event stage."
+      "note": "Shipment announced; the summary remains pending and the scan is registered."
+    },
+    {
+      "code": "RFS",
+      "stage": "accepted",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-10-04",
+      "note": "Goods received by the carrier."
+    },
+    {
+      "code": "SCA",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-10-04",
+      "note": "Loaded for delivery."
     }
   ]
 }

package/dist/cli/index.js

@@ -9,7 +9,7 @@ const help = `Universal Parcel Scraper
 
   parcel-scraper detect <number, link or text>
   parcel-scraper recognize <number>
-  parcel-scraper track <number> [--carrier <id>] [--postcode <value>] [--tracking-url <url>]
+  parcel-scraper track <number> [--carrier <id>] [--postcode <value>] [--tracking-url <url>] [--country-hint <code>]
   parcel-scraper carriers
   parcel-scraper serve [--host <address>] [--port <port>]
 
@@ -38,7 +38,7 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         throw new TypeError('Unknown command; use --help');
     const values = {};
     const positional = [];
-    const allowed = command === 'track' ? ['carrier', 'postcode', 'tracking-url'] : command === 'serve' ? ['host', 'port'] : [];
+    const allowed = command === 'track' ? ['carrier', 'postcode', 'tracking-url', 'country-hint'] : command === 'serve' ? ['host', 'port'] : [];
     for (let i = 0; i < args.length; i++) {
         const argument = args[i];
         if (!argument.startsWith('--')) {
@@ -91,7 +91,7 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
     if (command === 'recognize')
         print(await tracker.recognize(input));
     else
-        print(await tracker.track({ number: input, carrier: values.carrier, postcode: values.postcode, trackingUrl: values['tracking-url'] }));
+        print(await tracker.track({ number: input, carrier: values.carrier, postcode: values.postcode, trackingUrl: values['tracking-url'], countryHint: values['country-hint'] }));
     return 0;
 }
 /** What a failed command prints: a rejected input, setting or listener explains itself; anything else stays generic. */

package/dist/core/adapter/index.d.ts

@@ -8,6 +8,8 @@ export interface TrackingInput {
     trackingUrl?: string | null;
     /** The delivery postcode for carriers that need one; part of the tracking credential. */
     postcode?: string | null;
+    /** ISO country code or English name used only to retry an empty universal lookup; never shipment evidence. */
+    countryHint?: string | null;
     /**
      * The zone of the carrier the parcel is filed under, for universal providers
      * whose scan times name no zone they can be trusted with. When that

package/dist/core/adapter/track.js

@@ -28,7 +28,7 @@ export async function trackCarrier(carrier, input, options) {
         }
     }
     if (options.registry.adapterIdFor(carrier) === 'universal') {
-        return normalizeCarrierResult(await options.universal.fetch(input.number, input.postcode, { signal: options.signal, budgetMs: options.budgetMs }));
+        return normalizeCarrierResult(await options.universal.fetch(input.number, input.postcode, { signal: options.signal, budgetMs: options.budgetMs }, ...(input.countryHint === undefined ? [] : [input.countryHint])));
     }
     throw new RangeError(`No tracking adapter is registered for ${carrier}`);
 }

package/dist/facade/index.d.ts

@@ -24,6 +24,8 @@ export interface ParcelInput {
     number: string;
     carrier?: string;
     postcode?: string | null;
+    /** A destination or visitor country hint for an empty universal lookup; never shipment evidence. */
+    countryHint?: string | null;
     trackingUrl?: string | null;
 }
 export interface TrackingAttempt {

package/dist/facade/index.js

@@ -147,6 +147,8 @@ export function createTracker(options = {}) {
                     throw new TrackingError([], failureHint(new BudgetExceededError('Tracking', ms)));
             }
         }
+        if (input.countryHint != null && typeof input.countryHint !== 'string')
+            throw new TypeError('Invalid country hint');
         if (input.postcode != null && typeof input.postcode !== 'string')
             throw new TypeError('Invalid postcode');
         if (input.trackingUrl != null && typeof input.trackingUrl !== 'string')
@@ -188,7 +190,7 @@ export function createTracker(options = {}) {
             for (const candidate of plan.sources.filter(source => enabled.includes(source))) {
                 if (signal.aborted)
                     break;
-                result = await attempt(candidate, () => provider(candidate, async () => resolveResult(await universal.fetchSource(candidate, number, Math.min(remaining() + DEADLINE_SLACK_MS, universalSourceBudget(candidate)), fields.postcode, carrierTimezone(carrier) === 'UTC' ? null : carrierTimezone(carrier), signal)), signal));
+                result = await attempt(candidate, () => provider(candidate, async () => resolveResult(await universal.fetchSource(candidate, number, Math.min(remaining() + DEADLINE_SLACK_MS, universalSourceBudget(candidate)), fields.postcode, carrierTimezone(carrier) === 'UTC' ? null : carrierTimezone(carrier), signal, input.countryHint)), signal));
                 if (result) {
                     source = candidate;
                     break;

package/dist/providers/parcelsapp/adapter.d.ts

@@ -18,6 +18,6 @@ export declare class ParcelsAppTracker {
     readonly options: ParcelsAppOptions;
     private readonly http;
     constructor(options?: ParcelsAppOptions);
-    fetch(trackingNumber: string, budgetMs?: number, postcode?: string | null, timezone?: string | null, signal?: AbortSignal): Promise<CarrierResult>;
+    fetch(trackingNumber: string, budgetMs?: number, postcode?: string | null, timezone?: string | null, signal?: AbortSignal, countryHint?: string | null): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/providers/parcelsapp/adapter.js

@@ -20,7 +20,7 @@ import { capturedBodies, loadCapture } from '../shared/capture.js';
 import { universalCarrierHints } from '../shared/hints.js';
 import { event, isNotice, localEvent, numberOf, result } from '../shared/result.js';
 import { carrierScan, markReturnLeg } from '../shared/scans.js';
-import { PARCELSAPP_API, ParcelsAppHttpClient } from './http.js';
+import { PARCELSAPP_API, parcelsAppCountry, ParcelsAppHttpClient } from './http.js';
 const SOURCE = 'ParcelsApp';
 const MAX_EVENTS = 1000;
 export const PARCELSAPP_BUDGET_MS = 45_000;
@@ -327,13 +327,14 @@ export class ParcelsAppTracker {
         this.options = options;
         this.http = options.httpClient === undefined ? new ParcelsAppHttpClient(options.fetcher) : options.httpClient;
     }
-    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? PARCELSAPP_BUDGET_MS, postcode, timezone = null, signal) {
+    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? PARCELSAPP_BUDGET_MS, postcode, timezone = null, signal, countryHint) {
         const number = numberOf(trackingNumber);
         if (!Number.isFinite(budgetMs) || budgetMs < 1)
             throw new TypeError('ParcelsApp timeout must be positive');
         const deadline = performance.now() + budgetMs;
-        const request = async (remainingMs, signal) => {
-            const payload = await this.http.fetch(number, Math.max(1, Math.min(DIRECT_BUDGET_MS, Math.floor(remainingMs))), postcode, signal);
+        const country = parcelsAppCountry(countryHint);
+        const request = async (remainingMs, signal, manualCountry) => {
+            const payload = await this.http.fetch(number, Math.max(1, Math.min(DIRECT_BUDGET_MS, Math.floor(remainingMs))), postcode, signal, manualCountry);
             // This endpoint returns one shipment per POST, synchronously, with no
             // shared session or polling handle. Each retry keeps its own request
             // binding. Numberless browser captures never get this exemption.
@@ -350,13 +351,17 @@ export class ParcelsAppTracker {
                 id: 'retry',
                 enabled: this.http !== null,
                 // Uncached carrier aggregation can outlive a timed-out HTTP request.
-                // Retry that replayable read once; responses such as NO_DATA, input
-                // gates, aliases, challenges and HTTP errors do not qualify.
-                recovers: (error) => error instanceof UpstreamNetworkError && deadline - performance.now() > RETRY_DELAY_MS + 1,
-                run: async ({ signal }) => {
-                    await timers.setTimeout(RETRY_DELAY_MS, undefined, { signal });
+                // Retry a replayable network failure with the same input. An empty
+                // answer can instead try the caller's country once, as the website's
+                // selector does. Both share this step and the original lookup budget.
+                recovers: (error) => (error instanceof UpstreamNetworkError && deadline - performance.now() > RETRY_DELAY_MS + 1)
+                    || (country !== null && error instanceof NoHistoryError && deadline - performance.now() > 1),
+                run: async ({ signal, previousError }) => {
+                    const empty = previousError instanceof NoHistoryError;
+                    if (!empty)
+                        await timers.setTimeout(RETRY_DELAY_MS, undefined, { signal });
                     signal.throwIfAborted();
-                    return request(deadline - performance.now(), signal);
+                    return request(deadline - performance.now(), signal, empty ? country : null);
                 },
             }, {
                 id: 'trawl',
@@ -389,6 +394,6 @@ export const adapter = (environment) => {
     return {
         id: SOURCE,
         steps: ['direct', 'retry', 'trawl'],
-        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.postcode, input.timezone ?? null, context?.signal),
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.postcode, input.timezone ?? null, context?.signal, input.countryHint),
     };
 };

package/dist/providers/parcelsapp/http.d.ts

@@ -1,9 +1,11 @@
+/** The country selector uses English names, not ISO codes. */
+export declare function parcelsAppCountry(value: unknown): string | null;
 export declare const PARCELSAPP_API = "https://parcelsapp.com/api/v2/parcels";
 /** MurmurHash2 with the public website's seed, over ASCII protocol data. */
 export declare function parcelsAppChecksum(text: string): number;
-export declare function parcelsAppRequest(trackingNumber: string, postcode?: string | null): URLSearchParams;
+export declare function parcelsAppRequest(trackingNumber: string, postcode?: string | null, countryHint?: string | null): URLSearchParams;
 export declare class ParcelsAppHttpClient {
     readonly fetcher?: typeof fetch | undefined;
     constructor(fetcher?: typeof fetch | undefined);
-    fetch(trackingNumber: string, timeoutMs: number, postcode?: string | null, signal?: AbortSignal): Promise<unknown>;
+    fetch(trackingNumber: string, timeoutMs: number, postcode?: string | null, signal?: AbortSignal, countryHint?: string | null): Promise<unknown>;
 }

package/dist/providers/parcelsapp/http.js

@@ -1,5 +1,12 @@
 import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
 import { numberOf } from '../shared/result.js';
+import { countryCode } from '../../core/time/index.js';
+const COUNTRY_NAMES = new Intl.DisplayNames(['en'], { type: 'region' });
+/** The country selector uses English names, not ISO codes. */
+export function parcelsAppCountry(value) {
+    const code = countryCode(value);
+    return code && code !== 'ZZ' ? COUNTRY_NAMES.of(code) ?? null : null;
+}
 export const PARCELSAPP_API = 'https://parcelsapp.com/api/v2/parcels';
 // Public frontend protocol, verified 2026-09-12. No session or issued secret:
 // packs/js/application-aa19cda6a00923f7e330.js on dvow0vltefbxy.cloudfront.net.
@@ -29,7 +36,7 @@ export function parcelsAppChecksum(text) {
     hash = Math.imul(hash, 0x5bd1e995);
     return (hash ^ hash >>> 15) >>> 0;
 }
-export function parcelsAppRequest(trackingNumber, postcode) {
+export function parcelsAppRequest(trackingNumber, postcode, countryHint) {
     const number = numberOf(trackingNumber);
     // The bundle shifts ASCII by 2 * sum([1,2,8,4,5,6,7,5]) modulo 126,
     // URI-encodes it, then lets jQuery form-encode it a second time.
@@ -42,6 +49,9 @@ export function parcelsAppRequest(trackingNumber, postcode) {
     const zipcode = postcode?.trim();
     if (zipcode)
         params.set('extra[zipcode]', zipcode);
+    const country = parcelsAppCountry(countryHint);
+    if (country)
+        params.set('extra[manualCountry]', country);
     return params;
 }
 export class ParcelsAppHttpClient {
@@ -49,7 +59,7 @@ export class ParcelsAppHttpClient {
     constructor(fetcher) {
         this.fetcher = fetcher;
     }
-    async fetch(trackingNumber, timeoutMs, postcode, signal) {
+    async fetch(trackingNumber, timeoutMs, postcode, signal, countryHint) {
         const number = numberOf(trackingNumber);
         if (!Number.isFinite(timeoutMs) || timeoutMs < 1)
             throw new TypeError('ParcelsApp HTTP timeout must be positive');
@@ -60,7 +70,7 @@ export class ParcelsAppHttpClient {
                 Origin: 'https://parcelsapp.com', Referer: `https://parcelsapp.com/en/tracking/${number}`,
                 'X-Requested-With': 'XMLHttpRequest',
             },
-            body: parcelsAppRequest(number, postcode),
+            body: parcelsAppRequest(number, postcode, countryHint),
         }, { provider: 'ParcelsApp', fetcher: this.fetcher, timeoutMs: Math.floor(timeoutMs), maxBytes: 2_000_000 });
         return parseJsonBytes(bytes, 'ParcelsApp');
     }

package/dist/providers/universal.d.ts

@@ -56,10 +56,11 @@ export declare class UniversalTracker {
      * stored delivery postcode, if the user supplied one: it is forwarded into
      * every provider's track input. ParcelsApp submits it as extra[zipcode] on
      * its direct API request; the other providers currently do not consume it.
+     * `countryHint` lets ParcelsApp retry an empty answer with that country.
      * The caller's budget covers the whole chain and its signal ends it.
      */
-    fetch(trackingNumber: string, postcode?: string | null, context?: TrackingContext): Promise<CarrierResult>;
-    fetchSource(source: Source, trackingNumber: string, timeoutMs?: number, postcode?: string | null, timezone?: string | null, signal?: AbortSignal): Promise<CarrierResult>;
+    fetch(trackingNumber: string, postcode?: string | null, context?: TrackingContext, countryHint?: string | null): Promise<CarrierResult>;
+    fetchSource(source: Source, trackingNumber: string, timeoutMs?: number, postcode?: string | null, timezone?: string | null, signal?: AbortSignal, countryHint?: string | null): Promise<CarrierResult>;
     /** One provider adapter, built from this tracker's environment. */
     private provider;
     private environment;

package/dist/providers/universal.js

@@ -49,9 +49,10 @@ export class UniversalTracker {
      * stored delivery postcode, if the user supplied one: it is forwarded into
      * every provider's track input. ParcelsApp submits it as extra[zipcode] on
      * its direct API request; the other providers currently do not consume it.
+     * `countryHint` lets ParcelsApp retry an empty answer with that country.
      * The caller's budget covers the whole chain and its signal ends it.
      */
-    async fetch(trackingNumber, postcode, context = {}) {
+    async fetch(trackingNumber, postcode, context = {}, countryHint) {
         numberOf(trackingNumber);
         context.signal?.throwIfAborted();
         const deadline = context.budgetMs === undefined ? Infinity : performance.now() + context.budgetMs;
@@ -64,7 +65,7 @@ export class UniversalTracker {
                 continue;
             }
             try {
-                return await this.fetchSource(source, trackingNumber, Math.min(remaining, this.options.timeoutMs ?? universalSourceBudget(source)), postcode, null, context.signal);
+                return await this.fetchSource(source, trackingNumber, Math.min(remaining, this.options.timeoutMs ?? universalSourceBudget(source)), postcode, null, context.signal, countryHint);
             }
             catch (error) {
                 if (context.signal?.aborted)
@@ -74,12 +75,12 @@ export class UniversalTracker {
         }
         throw new UniversalTrackingError(failures);
     }
-    async fetchSource(source, trackingNumber, timeoutMs = this.options.timeoutMs ?? universalSourceBudget(source), postcode, timezone, signal) {
+    async fetchSource(source, trackingNumber, timeoutMs = this.options.timeoutMs ?? universalSourceBudget(source), postcode, timezone, signal, countryHint) {
         const number = numberOf(trackingNumber);
         if (this.options.browserLookup && (source === 'Postal Ninja' || source === 'Ship24')) {
             return await this.options.browserLookup(source, number);
         }
-        return await this.provider(source).track({ number, postcode: postcode ?? null, timezone: timezone ?? null }, { budgetMs: timeoutMs, signal });
+        return await this.provider(source).track({ number, postcode: postcode ?? null, timezone: timezone ?? null, countryHint: countryHint ?? null }, { budgetMs: timeoutMs, signal });
     }
     /** One provider adapter, built from this tracker's environment. */
     provider(source) {

package/dist/server/index.js

@@ -142,7 +142,7 @@ export function createTrackingServer(options = {}) {
         const number = normalizeTrackingNumber(input.number);
         const detected = detectCarrierMatch(number);
         input = { ...input, number, carrier: input.carrier ?? (detected.confidence === 'high' ? detected.carrier : undefined) };
-        const key = createHash('sha256').update(JSON.stringify([input.number, input.carrier, input.postcode, input.trackingUrl])).digest('hex');
+        const key = createHash('sha256').update(JSON.stringify([input.number, input.carrier, input.postcode, input.trackingUrl, input.countryHint])).digest('hex');
         const previous = cache.get(key);
         if (previous && previous.until > now()) {
             if (previous.error)
@@ -261,7 +261,7 @@ export function createTrackingServer(options = {}) {
             }
             const input = await body(request);
             const allowed = path === '/v1/detect' ? ['text'] : path === '/v1/recognize' ? ['number', 'budgetMs']
-                : ['number', 'carrier', 'postcode', 'trackingUrl', 'budgetMs'];
+                : ['number', 'carrier', 'postcode', 'trackingUrl', 'countryHint', 'budgetMs'];
             if (Object.keys(input).some(key => !allowed.includes(key)))
                 throw new HttpError(400, 'Unknown request field');
             if (path === '/v1/detect') {
@@ -275,7 +275,7 @@ export function createTrackingServer(options = {}) {
                 return;
             }
             const result = await tracked({ number: input.number, carrier: input.carrier,
-                postcode: input.postcode, trackingUrl: input.trackingUrl }, input.budgetMs);
+                postcode: input.postcode, trackingUrl: input.trackingUrl, countryHint: input.countryHint }, input.budgetMs);
             json(response, 200, result);
         }
         catch (error) {

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.3.4"
+    "version": "0.4.0"
   },
   "paths": {
     "/health": {
@@ -539,6 +539,13 @@
             "type": "integer",
             "minimum": 1,
             "maximum": 120000
+          },
+          "countryHint": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Country code or English name used only to retry an empty universal lookup."
           }
         },
         "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.3.4-main.317",
+  "version": "0.4.0-main.319",
   "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
   "type": "module",
   "license": "Apache-2.0",