universal-parcel-scraper 0.133.0 → 0.133.1

package/dist/carriers/apc-overnight/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -54,7 +55,7 @@ function searchPage($, html, number) {
     const notice = notices.length === 1 ? clean(notices.text(), 200) : '';
     // The page puts the identifier it was asked for back into its search field.
     const fields = $('input#ConsignmentNumber');
-    const echoed = fields.length === 1 ? normalizeTrackingNumber(clean(fields.attr('value'), 80)) : '';
+    const echoed = fields.length === 1 ? returnedTrackingNumber(fields.attr('value')) : '';
     if (notice === NOT_FOUND || notice === INVALID) {
         if (echoed !== number)
             throw new SchemaError(PROVIDER, 'APC Overnight answered for a different number');

package/dist/carriers/asendia/probe.js

@@ -21,6 +21,7 @@
  * event from an explicit allowlist (time, harmonized wording, scanning
  * location, harmonized code) and copies nothing else.
  */
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { createHash } from 'node:crypto';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
@@ -140,7 +141,7 @@ function parseTenantConfig(payload) {
 function responseIdentifier(parcel) {
     for (const value of [parcel.tracking_id, parcel.upper_tracking_id]) {
         try {
-            return normalizeAsendiaTrackingNumber(cleanScalar(value, 64));
+            return normalizeAsendiaTrackingNumber(returnedTrackingNumber(value, true));
         }
         catch {
             // Try the alternate provider field.

package/dist/carriers/cdek/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NoHistoryError, SchemaError } from '../../core/errors/index.js';
 import { languageStageStatus } from '../../core/status/index.js';
@@ -71,8 +72,8 @@ export function parseCdek(payload, raw) {
     const data = payload.data;
     if (!isRecord(data))
         throw new SchemaError(PROVIDER, 'CDEK did not return an order');
-    const order = normalizeTrackingNumber(clean(data.orderNumber, 40));
-    const outer = payload.orderNumber === undefined ? order : normalizeTrackingNumber(clean(payload.orderNumber, 40));
+    const order = returnedTrackingNumber(data.orderNumber);
+    const outer = payload.orderNumber === undefined ? order : returnedTrackingNumber(payload.orderNumber);
     if (!ISSUED.test(order) || outer !== order)
         throw new SchemaError(PROVIDER, 'CDEK returned an order without its number');
     // CDEK finds an order by a number it links to it and answers with the order's own number.

package/dist/carriers/correos-de-mexico/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
 import { ChallengeError, IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
@@ -125,7 +126,7 @@ export function readCorreosDeMexicoPage(html, rawNumber, askedYear) {
     const guia = form.find('input#Guia[name="Guia"]');
     if (guia.length !== 1)
         throw new SchemaError(PROVIDER, 'Correos de México tracking form changed');
-    if (normalizeTrackingNumber(clean(guia.attr('value'), 80)) !== number) {
+    if (returnedTrackingNumber(guia.attr('value')) !== number) {
         throw new SchemaError(PROVIDER, 'Correos de México answered for a different number');
     }
     const options = form.find('select#Periodo[name="Periodo"] > option');

package/dist/carriers/cyprus-post/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -192,7 +193,7 @@ function itemFor($, html, number) {
     const panel = panels.first();
     const titles = panel.find('.panel-heading .panel-title a');
     const bodies = panel.children('.panel-collapse');
-    if (titles.length !== 1 || normalizeTrackingNumber(clean(titles.text(), 80)) !== number
+    if (titles.length !== 1 || returnedTrackingNumber(titles.text()) !== number
         || bodies.length !== 1 || bodies.attr('id') !== `collapse_${number}`) {
         throw new SchemaError(PROVIDER, 'Cyprus Post answered for a different item');
     }

package/dist/carriers/dai-post/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { ChallengeError, IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -133,7 +134,7 @@ function scanRows(rows) {
             if (props && node[1] === 'input' && props.name === 'tracknbr' && typeof props.defaultValue === 'string') {
                 const value = flightText(props.defaultValue);
                 if (value !== undefined)
-                    echoed.add(normalizeTrackingNumber(clean(value, 200)));
+                    echoed.add(returnedTrackingNumber(value));
             }
             for (const child of node)
                 stack.push(child);

package/dist/carriers/dao/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { carrierIdFromPartner } from '../../core/catalog/hints.js';
 import { isValidSscc, normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -30,7 +31,7 @@ export function normalizeDaoNumber(raw) {
 }
 /** The parcel number the reply names, in the forms DAO issues. */
 function issued(value) {
-    const barcode = normalizeTrackingNumber(cleanScalar(value, 40));
+    const barcode = returnedTrackingNumber(value, true);
     return /^(?:00\d{18}|7\d{12}|\d{9})$/.test(barcode) ? barcode : '';
 }
 /** A clock as a wall time, validated. The reply gives no offset. */
@@ -76,7 +77,7 @@ function scanOf(row, index) {
 }
 /** The partner and number a parcel sent abroad is tracked under, as the page links them. */
 function abroad(parcel, number) {
-    const partnerNumber = normalizeTrackingNumber(clean(parcel.dist_barcode, 64));
+    const partnerNumber = returnedTrackingNumber(parcel.dist_barcode);
     if (!/^[A-Z0-9]{4,40}$/.test(partnerNumber) || partnerNumber === number)
         return {};
     const partner = carrierIdFromPartner('', clean(parcel.external_tracking, 500));

package/dist/carriers/dhl-ecommerce-pl/adapter.js

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
 import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
-import { BudgetExceededError, IndeterminateError } from '../../core/errors/index.js';
+import { BudgetExceededError, ChallengeError, IndeterminateError, UpstreamHttpError, UpstreamNetworkError } 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 { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
+import { decodeText, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { normalizeDhlEcommercePlNumber, parseDhlEcommercePl, parseDhlEcommercePlChallenge, parseDhlEcommercePlRejection } from './parser.js';
 const PROVIDER = 'DHL eCommerce Poland';
 // The guest routes behind mojdhl.pl. They return the current status and none
@@ -37,47 +38,68 @@ export class DhlEcommercePlTracker {
     fetch(raw, context = {}) {
         const number = normalizeDhlEcommercePlNumber(raw);
         const budgetMs = context.budgetMs ?? 15_000;
+        const read = async (signal, remainingMs) => {
+            signal.throwIfAborted();
+            // One deadline covers the challenge, its solution and the lookup.
+            const deadline = performance.now() + remainingMs;
+            const left = () => {
+                const ms = Math.floor(deadline - performance.now());
+                if (ms <= 0)
+                    throw new BudgetExceededError(PROVIDER, budgetMs);
+                return ms;
+            };
+            // A page in place of JSON is a block, whatever its status says.
+            const json = (bytes) => {
+                try {
+                    return parseJsonBytes(bytes, PROVIDER);
+                }
+                catch {
+                    if (/Request Rejected|The requested URL was rejected|Access Denied|cf-chl-|_cf_chl_opt|cf-turnstile|Incapsula incident|<title>\s*(?:Just a moment|Attention Required)/i.test(decodeText(bytes.subarray(0, 64000)))) {
+                        throw new ChallengeError(PROVIDER, 'DHL eCommerce Poland returned a browser challenge');
+                    }
+                    throw new IndeterminateError(PROVIDER, 'DHL eCommerce Poland returned a page instead of tracking JSON');
+                }
+            };
+            // The signed per-request proof stays out of failure diagnostics. Each
+            // retry obtains a fresh challenge rather than replaying a spent proof.
+            const request = async (url, init, options) => {
+                try {
+                    return await fetchBounded(url, { ...init, signal }, options);
+                }
+                catch (error) {
+                    if (error instanceof UpstreamHttpError)
+                        throw new UpstreamHttpError(PROVIDER, error.status, error.retryAfterMs);
+                    if (error instanceof UpstreamNetworkError)
+                        throw new UpstreamNetworkError(PROVIDER, new Error('DHL eCommerce Poland tracking request failed'));
+                    throw error;
+                }
+            };
+            const headers = { Accept: 'application/json', 'Accept-Language': 'en', 'User-Agent': userAgentOf(this.options.userAgent) };
+            const issued = await request(`${BASE}/auth/captcha/challenge`, { signal, headers }, {
+                provider: PROVIDER, timeoutMs: left(), maxBytes: 20_000, fetcher: this.options.fetcher,
+            });
+            const proof = await solveDhlEcommercePlChallenge(parseDhlEcommercePlChallenge(json(issued.bytes)), signal, deadline, budgetMs);
+            signal.throwIfAborted();
+            const { response, bytes } = await request(`${BASE}/shipment/status`, { method: 'POST', signal,
+                headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ number1: number, 'captcha-payload': proof }) }, {
+                provider: PROVIDER, timeoutMs: left(), maxBytes: 500_000, allowHttpStatuses: [400, 422], fetcher: this.options.fetcher,
+            });
+            if (response.status === 422)
+                return parseDhlEcommercePlRejection(json(bytes));
+            // A 400 is the portal refusing the proof: nothing was looked up.
+            if (response.status !== 200)
+                throw new IndeterminateError(PROVIDER, 'DHL eCommerce Poland returned an inconclusive tracking response');
+            return parseDhlEcommercePl(json(bytes), number);
+        };
         return runSteps({ carrier: 'dhl-ecommerce-pl', budgetMs, signal: context.signal,
-            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
-                    signal.throwIfAborted();
-                    // One deadline covers the challenge, its solution and the lookup.
-                    const deadline = performance.now() + remainingMs;
-                    const left = () => {
-                        const ms = Math.floor(deadline - performance.now());
-                        if (ms <= 0)
-                            throw new BudgetExceededError(PROVIDER, budgetMs);
-                        return ms;
-                    };
-                    // A page in place of JSON is a block, whatever its status says.
-                    const json = (bytes) => {
-                        try {
-                            return parseJsonBytes(bytes, PROVIDER);
-                        }
-                        catch (cause) {
-                            throw new IndeterminateError(PROVIDER, 'DHL eCommerce Poland returned a page instead of tracking JSON', { cause });
-                        }
-                    };
-                    const headers = { Accept: 'application/json', 'Accept-Language': 'en', 'User-Agent': userAgentOf(this.options.userAgent) };
-                    const issued = await fetchBounded(`${BASE}/auth/captcha/challenge`, { signal, headers }, {
-                        provider: PROVIDER, timeoutMs: left(), maxBytes: 20_000, fetcher: this.options.fetcher,
-                    });
-                    const proof = await solveDhlEcommercePlChallenge(parseDhlEcommercePlChallenge(json(issued.bytes)), signal, deadline, budgetMs);
-                    signal.throwIfAborted();
-                    const { response, bytes } = await fetchBounded(`${BASE}/shipment/status`, { method: 'POST', signal,
-                        headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ number1: number, 'captcha-payload': proof }) }, {
-                        provider: PROVIDER, timeoutMs: left(), maxBytes: 500_000, allowHttpStatuses: [400, 422], fetcher: this.options.fetcher,
-                    });
-                    if (response.status === 422)
-                        return parseDhlEcommercePlRejection(json(bytes));
-                    // A 400 is the portal refusing the proof: nothing was looked up.
-                    if (response.status !== 200)
-                        throw new IndeterminateError(PROVIDER, 'DHL eCommerce Poland returned an inconclusive tracking response');
-                    return parseDhlEcommercePl(json(bytes), number);
-                } }]);
+            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 DhlEcommercePlTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
-    return { id: 'dhl-ecommerce-pl', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+    return { id: 'dhl-ecommerce-pl', recordsSteps: true, steps: ['direct', 'retry'], track: (input, context) => tracker.fetch(input.number, context),
         recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeDhlEcommercePlNumber(number))) };
 };

package/dist/carriers/dhl-ecommerce-pl/carrier.json

@@ -20,7 +20,8 @@
     "mode": "automatic",
     "adapter": "dhl-ecommerce-pl",
     "steps": [
-      "direct"
+      "direct",
+      "retry"
     ],
     "recognition": {
       "rank": 620

package/dist/carriers/dsv/parser.js

@@ -1,5 +1,6 @@
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { languageStageStatus } from '../../core/status/index.js';
 import { clean, cleanScalar } from '../../core/transport/index.js';
@@ -31,14 +32,14 @@ function ownIds(shipment) {
     const ids = new Set();
     const calculated = Array.isArray(shipment.calculatedShipmentId) ? shipment.calculatedShipmentId : [];
     for (const value of [shipment.mainTmsShipmentId, shipment.shipmentId, shipment.bookingId, ...calculated]) {
-        const id = normalizeTrackingNumber(cleanScalar(value, 80));
+        const id = returnedTrackingNumber(value, true);
         if (id)
             ids.add(id);
     }
     return ids;
 }
 function shipmentOf(entry, own) {
-    const key = clean(entry.randomIdentifier, 80);
+    const key = typeof entry.randomIdentifier === 'string' ? entry.randomIdentifier : '';
     if (!KEY.test(key))
         throw new SchemaError(PROVIDER, 'myDSV returned a shipment without its key');
     return { key, mode: clean(entry.modeOfTransport, 40).toUpperCase(), own };
@@ -61,7 +62,7 @@ export function pickDsvShipment(payload, rawNumber) {
     const own = new Map();
     for (const entry of entries) {
         if (ownIds(entry).has(number))
-            own.set(clean(entry.randomIdentifier, 80), entry);
+            own.set(shipmentOf(entry, true).key, entry);
     }
     if (own.size === 1)
         return shipmentOf([...own.values()][0], true);
@@ -82,7 +83,7 @@ export function confirmDsvShipment(payload, rawNumber) {
     const number = normalizeDsvNumber(rawNumber);
     if (!isRecord(payload))
         throw new SchemaError(PROVIDER, 'myDSV did not return the shipment');
-    if (ownIds(payload).has(number) || normalizeTrackingNumber(cleanScalar(payload.houseBillNumber, 80)) === number)
+    if (ownIds(payload).has(number) || returnedTrackingNumber(payload.houseBillNumber, true) === number)
         return;
     throw new IndeterminateError(PROVIDER, 'The number matched only a reference of a DSV shipment', { reason: 'reference_only' });
 }

package/dist/carriers/dynalogic/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { languageStageStatus } from '../../core/status/index.js';
@@ -50,7 +51,7 @@ export function parseDynalogic(payload, rawNumber) {
         throw new SchemaError(PROVIDER, 'Dynalogic returned an invalid order reply');
     }
     const order = payload.data;
-    const answered = typeof order.TrackAndTraceNumber === 'string' ? normalizeTrackingNumber(clean(order.TrackAndTraceNumber, 64)) : '';
+    const answered = typeof order.TrackAndTraceNumber === 'string' ? returnedTrackingNumber(order.TrackAndTraceNumber) : '';
     if (!answered)
         throw new SchemaError(PROVIDER, 'Dynalogic returned an order without its number');
     // The service also finds an order by the merchant's order number or its end;

package/dist/carriers/express-one/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -120,7 +121,7 @@ export function parseExpressOne(html, raw, status = 200) {
     if (status === 404 || !blocks.length) {
         const notice = clean(notices.find('p b').first().text(), 200);
         if (status === 404 && !blocks.length && notices.length === 1 && ABSENT.has(notice)
-            && normalizeTrackingNumber(clean($('input#plc_number').val(), 64)) === number)
+            && returnedTrackingNumber($('input#plc_number').val()) === number)
             throw new NotFoundError(PROVIDER);
         throw new IndeterminateError(PROVIDER, 'Express One did not return the parcel');
     }

package/dist/carriers/fan-courier/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -42,14 +43,14 @@ export function parseFanCourier(payload, raw) {
         const message = clean(payload.message, 200).toLowerCase().replace(/\.$/, '');
         if (!ABSENT.has(message))
             throw new IndeterminateError(PROVIDER, 'FAN Courier did not return the AWB');
-        if (normalizeTrackingNumber(cleanScalar(payload.content, 64)) !== number) {
+        if (returnedTrackingNumber(payload.content, true) !== number) {
             throw new SchemaError(PROVIDER, 'FAN Courier answered for a different number');
         }
         throw new NotFoundError(PROVIDER);
     }
     if (typeof payload.awbNumber !== 'string' && typeof payload.awbNumber !== 'number')
         throw new SchemaError(PROVIDER);
-    if (normalizeTrackingNumber(cleanScalar(payload.awbNumber, 64)) !== number) {
+    if (returnedTrackingNumber(payload.awbNumber, true) !== number) {
         throw new SchemaError(PROVIDER, 'FAN Courier answered for a different AWB');
     }
     const rows = payload.events;

package/dist/carriers/foxpost/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -72,7 +73,7 @@ export function parseFoxpost(html, raw) {
     }
     if (!shown.length && !rows.length)
         throw new IndeterminateError(PROVIDER, 'Foxpost did not return a parcel');
-    if (shown.length !== 1 || normalizeTrackingNumber(clean(shown.text(), 80)) !== number) {
+    if (shown.length !== 1 || returnedTrackingNumber(shown.text()) !== number) {
         throw new SchemaError(PROVIDER, 'Foxpost returned a different parcel');
     }
     if ($('ul.parcel-status-items__list').length !== 1)

package/dist/carriers/gebrueder-weiss/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { DELIVERY_POSTCODE, deliveryPostcodeText } from '../../core/catalog/postcode.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -53,7 +54,7 @@ export function normalizeGebruederWeissPostcode(raw) {
 function carries(order, number) {
     const references = Array.isArray(order.customer_reference) ? order.customer_reference : [];
     return [order.order_id, order.request_order_id, ...references]
-        .some((value) => normalizeTrackingNumber(cleanScalar(value, 100)) === number);
+        .some((value) => returnedTrackingNumber(value, true) === number);
 }
 /** The branch a scan happened at, as "Town, AT", and its country. */
 function placeOf(location) {

package/dist/carriers/gls-it/parser.js

@@ -1,5 +1,6 @@
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { returnedTrackingNumber } from '../../core/detection/returned.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';
@@ -26,7 +27,7 @@ function records(value) {
     return Array.isArray(value) ? value.filter(isRecord) : [];
 }
 function shipmentNumber(row) {
-    return typeof row.tuNo === 'string' ? normalizeTrackingNumber(clean(row.tuNo, 40)) : '';
+    return typeof row.tuNo === 'string' ? returnedTrackingNumber(row.tuNo) : '';
 }
 /** The row's own count of parcels: the first row of a several-row reply is the shipment the page shows above its parcels. */
 function isShipmentOverview(row) {

package/dist/carriers/go-express/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -54,7 +55,7 @@ function linkedNumber($) {
         return null;
     try {
         const reference = new URL(links.attr('data-link') ?? '').searchParams.getAll('reference');
-        return reference.length === 1 ? normalizeTrackingNumber(clean(reference[0], 80)) : null;
+        return reference.length === 1 ? returnedTrackingNumber(reference[0]) : null;
     }
     catch {
         return null;

package/dist/carriers/hrvatska-posta/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -81,7 +82,7 @@ export function parseHrvatskaPosta(html, rawNumber) {
     if (header.length !== 1 || named.length !== 1 || label !== NUMBER_LABEL) {
         throw new SchemaError(PROVIDER, 'Hrvatska pošta did not answer in English');
     }
-    if (normalizeTrackingNumber(clean(named.text(), 80)) !== number) {
+    if (returnedTrackingNumber(named.text()) !== number) {
         throw new SchemaError(PROVIDER, 'Hrvatska pošta answered for a different number');
     }
     const groups = root.find('div.track__n__trace-events-content > div.event__status__item');

package/dist/carriers/japan-post/adapter.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -68,7 +69,7 @@ export function parse(html, trackingNumber) {
         const rows = result.find('tr').filter((_, row) => $(row).children('td').length > 0);
         const cells = rows.children('td');
         if (!details.length && !history.length && result.length === 1 && rows.length === 1 && cells.length === 2
-            && normalizeTrackingNumber(clean(cells.eq(0).text())) === number
+            && returnedTrackingNumber(cells.eq(0).text()) === number
             && clean(cells.eq(1).text()) === '** Your item was not found. Confirm your item number and ask at your local office.') {
             throw new NotFoundError(PROVIDER);
         }

package/dist/carriers/jd-logistics/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
@@ -127,7 +128,7 @@ export function parseJdLogistics(payload, raw) {
     if (!payload.data.length)
         throw new IndeterminateError(PROVIDER, 'JD Logistics returned no international history');
     if (payload.data.length !== 1 || !isRecord(payload.data[0])
-        || normalizeTrackingNumber(clean(payload.data[0].waybillNo, 64)) !== number) {
+        || returnedTrackingNumber(payload.data[0].waybillNo) !== number) {
         throw new SchemaError(PROVIDER, 'JD Logistics returned a different or ambiguous shipment');
     }
     const item = payload.data[0];

package/dist/carriers/kuehne-nagel/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -111,8 +112,8 @@ export function parseKuehneNagelSearch(payload, rawNumber) {
         const kind = clean(group.kind, 60);
         for (const shipment of group.shipments) {
             const id = isRecord(shipment) ? cleanScalar(shipment.id, 20) : '';
-            const trackingNumber = isRecord(shipment) ? normalizeTrackingNumber(clean(shipment.trackingNumber, 40)) : '';
-            if (!isRecord(shipment) || !ID.test(id) || !trackingNumber) {
+            const trackingNumber = isRecord(shipment) ? returnedTrackingNumber(shipment.trackingNumber) : '';
+            if (!isRecord(shipment) || !ID.test(id) || !trackingNumber || trackingNumber.length > 40) {
                 throw new SchemaError(PROVIDER, 'Kuehne+Nagel returned a shipment without its id or tracking number');
             }
             const exact = kind === TRACKING_NUMBER && trackingNumber === number;

package/dist/carriers/landmark-global/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { carrierIdFromPartner } from '../../core/catalog/hints.js';
@@ -48,7 +49,7 @@ export function parseLandmark(html, rawNumber) {
     const canonical = identities.length === 1 ? clean(identities.next('div').text(), 64) : '';
     // A merchant reference must be the parcel's order or package reference; its LTN then names the parcel.
     const references = $('.shipment-details-col h6').filter((_, node) => ['Order Reference', 'Package Reference'].includes(clean($(node).text())))
-        .map((_, node) => normalizeTrackingNumber(clean($(node).next('div').text(), 100))).get();
+        .map((_, node) => returnedTrackingNumber($(node).next('div').text())).get();
     if (identities.length !== 1 || (merchant ? !/^LTN\d{8,9}$/.test(canonical) || !references.includes(number)
         : canonical !== number.replace(/N1$/, '')))
         throw new SchemaError('Landmark Global', 'Landmark returned a different or ambiguous parcel');

package/dist/carriers/maltapost/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -47,7 +48,7 @@ function barcodeOf(value) {
         return '';
     if (typeof value !== 'string')
         throw new SchemaError(PROVIDER, 'MaltaPost returned an invalid barcode');
-    return normalizeTrackingNumber(clean(value, 80));
+    return returnedTrackingNumber(value);
 }
 /** The scan's wording, its reason and the action that follows, as the tracking page lists them. */
 function wordingOf(row) {

package/dist/carriers/matkahuolto/parser.js

@@ -1,5 +1,6 @@
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, isValidSscc, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { lastMovement } from '../../core/result/pickup.js';
 import { languageStageStatus } from '../../core/status/index.js';
@@ -102,7 +103,7 @@ export function parseMatkahuolto(reply, raw) {
             throw new NotFoundError(PROVIDER);
         throw new IndeterminateError(PROVIDER, 'Matkahuolto returned an unexpected not-found reply');
     }
-    if (typeof reply.parcelNumber !== 'string' || !sameNumber(normalizeTrackingNumber(clean(reply.parcelNumber, 60)), number)) {
+    if (typeof reply.parcelNumber !== 'string' || !sameNumber(returnedTrackingNumber(reply.parcelNumber), number)) {
         throw new SchemaError(PROVIDER, 'Matkahuolto answered for a different consignment');
     }
     const rows = reply.trackingEvents;

package/dist/carriers/meest/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { carrierIdFromPartner } from '../../core/catalog/hints.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
@@ -80,8 +81,8 @@ function rowOf(item, index) {
         code,
         description,
         location: [city, country].filter(Boolean).join(', '),
-        own: ['ShipmentNumber', 'ShipmentNumberSender', 'Barcode'].map(name => normalizeTrackingNumber(clean(field(item, name), 64))),
-        transit: normalizeTrackingNumber(clean(field(item, 'ShipmentNumberTransit'), 64)),
+        own: ['ShipmentNumber', 'ShipmentNumberSender', 'Barcode'].map(name => returnedTrackingNumber(field(item, name))),
+        transit: returnedTrackingNumber(field(item, 'ShipmentNumberTransit')),
         destination: clean(field(item, 'CountryDel'), 8),
         // The page hides these, and the Chinese consolidator's own registration before Meest's.
         hidden: code === HIDDEN_CODE || (clean(field(item, 'AgentCode'), 40) === 'MCHINA' && field(item, 'ActionMessages').trim() === 'Зареєстровано'),

package/dist/carriers/nova-poshta/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { explicitOffsetTime, zonedTime } from '../../core/time/index.js';
@@ -185,7 +186,7 @@ function partnerOf(payload) {
         for (const reference of references) {
             if (!isRecord(reference) || typeof reference.name !== 'string' || !Object.hasOwn(PARTNERS, reference.name))
                 continue;
-            const number = normalizeTrackingNumber(clean(reference.number, 64));
+            const number = returnedTrackingNumber(reference.number);
             if (/^[A-Z0-9]{8,40}$/.test(number))
                 return { delivery_carrier: PARTNERS[reference.name], delivery_tracking_number: number };
         }

package/dist/carriers/passport/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { carrierIdFromPartner } from '../../core/catalog/hints.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
@@ -52,7 +53,7 @@ function shipmentOf(html, number) {
     if (!isRecord(shipment) || typeof shipment.tracking_code !== 'string') {
         throw new SchemaError(PROVIDER, 'Passport returned a shipment without its tracking number');
     }
-    if (normalizeTrackingNumber(clean(shipment.tracking_code, 64)) !== number) {
+    if (returnedTrackingNumber(shipment.tracking_code) !== number) {
         throw new SchemaError(PROVIDER, 'Passport returned another shipment');
     }
     const bought = shipment.time_bought;

package/dist/carriers/speedy/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { ChallengeError, InvalidInputError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
 import { lastMovement } from '../../core/result/pickup.js';
@@ -66,7 +67,7 @@ function partnerOf(mappings, number) {
         if (!isRecord(mapping) || mapping.mappingFor !== 'RECEIVER')
             continue;
         const carrier = PARTNERS[clean(mapping.externalCarrier, 32)];
-        const reference = normalizeTrackingNumber(cleanScalar(mapping.barcode, 64));
+        const reference = returnedTrackingNumber(mapping.barcode, true);
         if (carrier && /^[A-Z0-9]{4,40}$/.test(reference) && reference !== number) {
             return { delivery_carrier: carrier, delivery_tracking_number: reference };
         }

package/dist/carriers/xdp/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { DELIVERY_POSTCODE, deliveryPostcodeText } from '../../core/catalog/postcode.js';
@@ -103,7 +104,7 @@ export function parseXdp(html, raw) {
     const field = $('form#trackform input#c');
     if (field.length !== 1)
         throw new IndeterminateError(PROVIDER, 'XDP did not return its tracking page');
-    if (normalizeTrackingNumber(clean(field.attr('value'), 64)) !== number) {
+    if (returnedTrackingNumber(field.attr('value')) !== number) {
         throw new SchemaError(PROVIDER, 'XDP answered for a different consignment');
     }
     const cells = $('#leftCol tr').toArray().map((tr) => $(tr).children('td'))

package/dist/carriers/yto/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { zonedTime } from '../../core/time/index.js';
@@ -21,7 +22,7 @@ export function parseYto(payload, trackingNumber) {
         throw new SchemaError(PROVIDER, 'YTO returned an invalid shipment list');
     if (!payload.length)
         throw new IndeterminateError(PROVIDER, 'YTO returned no shipment details');
-    if (payload.length !== 1 || !isRecord(payload[0]) || normalizeTrackingNumber(clean(payload[0].waybillNo, 64)) !== number) {
+    if (payload.length !== 1 || !isRecord(payload[0]) || returnedTrackingNumber(payload[0].waybillNo) !== number) {
         throw new SchemaError(PROVIDER, 'YTO returned missing or ambiguous shipment identity');
     }
     const item = payload[0];
@@ -39,7 +40,7 @@ export function parseYto(payload, trackingNumber) {
     // The official client uses the first row as current. Read oldest first to
     // preserve a return leg when later scans use ordinary movement/signature codes.
     for (const raw of [...history].reverse()) {
-        if (!isRecord(raw) || normalizeTrackingNumber(clean(raw.waybillNo, 64)) !== number) {
+        if (!isRecord(raw) || returnedTrackingNumber(raw.waybillNo) !== number) {
             throw new SchemaError(PROVIDER, 'YTO returned mixed or incomplete shipment history');
         }
         const code = clean(raw.opCode, 32);

package/dist/carriers/yunda/parser.js

@@ -1,3 +1,4 @@
+import { returnedTrackingNumber } from '../../core/detection/returned.js';
 import { normalizeTrackingNumber } from '../../core/detection/index.js';
 import { ChallengeError, IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { zonedTime } from '../../core/time/index.js';
@@ -58,7 +59,7 @@ export function parseYunda(payload, trackingNumber) {
     const events = [];
     let returning = false;
     for (const raw of history.gn) {
-        if (!isRecord(raw) || normalizeTrackingNumber(clean(raw.mailNo, 64)) !== number) {
+        if (!isRecord(raw) || returnedTrackingNumber(raw.mailNo) !== number) {
             throw new SchemaError(PROVIDER, 'Yunda returned mixed or incomplete scan identities');
         }
         const label = clean(raw.status, 100);

package/dist/core/detection/returned.d.ts

@@ -0,0 +1,2 @@
+/** Normalize a complete provider identifier; display-text limits must never hide a suffix. */
+export declare function returnedTrackingNumber(value: unknown, allowNumeric?: boolean): string;

package/dist/core/detection/returned.js

@@ -0,0 +1,7 @@
+import { normalizeTrackingNumber } from './normalize.js';
+/** Normalize a complete provider identifier; display-text limits must never hide a suffix. */
+export function returnedTrackingNumber(value, allowNumeric = false) {
+    const text = typeof value === 'string' ? value
+        : allowNumeric && typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? String(value) : '';
+    return text.length <= 4096 ? normalizeTrackingNumber(text) : '';
+}

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.133.0"
+    "version": "0.133.1"
   },
   "paths": {
     "/health": {

package/package.json

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