universal-parcel-scraper 0.636.0-main.2999 → 0.637.1

package/README.md

@@ -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 16,379 such statuses, each filed under one stage.
+The carrier folders record 16,380 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/ctt-express/adapter.js

@@ -1,10 +1,14 @@
 import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
 import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
+import { firstAttemptMs, isNetworkFailure } from '../../core/runner/networkRetry.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
-import { normalizeCttExpressNumber, parseCttExpress } from './parser.js';
+import { CttExpressErrorReply, normalizeCttExpressNumber, parseCttExpress } from './parser.js';
 const ENDPOINT = 'https://wct.cttexpress.com/p_track_redis_v2.php';
+/** A body that is not JSON. */
+class UnreadableReply extends SchemaError {
+}
 export class CttExpressTracker {
     options;
     constructor(options = {}) {
@@ -12,30 +16,38 @@ export class CttExpressTracker {
     }
     fetch(raw, context = {}) {
         const number = normalizeCttExpressNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            signal.throwIfAborted();
+            const url = new URL(ENDPOINT);
+            url.searchParams.set('sc', number);
+            const { response, bytes } = await fetchBounded(url, { signal, headers: { Accept: 'application/json',
+                    Origin: 'https://shipping-tracking.production.cloud2.cttexpress.com', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: 'CTT Express', timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: 1_000_000,
+                allowHttpStatuses: [404, 410], fetcher: this.options.fetcher });
+            if (response.status !== 200)
+                throw new IndeterminateError('CTT Express', 'CTT Express tracking endpoint is unavailable');
+            let payload;
+            try {
+                payload = parseJsonBytes(bytes, 'CTT Express');
+            }
+            catch (cause) {
+                throw new UnreadableReply('CTT Express', 'CTT Express returned invalid tracking JSON', { cause });
+            }
+            return parseCttExpress(payload, number);
+        };
+        // A few percent of lookups get an error reply or a body that is not JSON, and the same
+        // parcel reads normally on the next poll. Those, like a request that fails to reach the
+        // service, are read once more.
         return runSteps({ carrier: 'ctt-express', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
-            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
-                    signal.throwIfAborted();
-                    const url = new URL(ENDPOINT);
-                    url.searchParams.set('sc', number);
-                    const { response, bytes } = await fetchBounded(url, { signal, headers: { Accept: 'application/json',
-                            Origin: 'https://shipping-tracking.production.cloud2.cttexpress.com', 'User-Agent': userAgentOf(this.options.userAgent),
-                        } }, { provider: 'CTT Express', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
-                        allowHttpStatuses: [404, 410], fetcher: this.options.fetcher });
-                    if (response.status !== 200)
-                        throw new IndeterminateError('CTT Express', 'CTT Express tracking endpoint is unavailable');
-                    let payload;
-                    try {
-                        payload = parseJsonBytes(bytes, 'CTT Express');
-                    }
-                    catch (cause) {
-                        throw new SchemaError('CTT Express', 'CTT Express returned invalid tracking JSON', { cause });
-                    }
-                    return parseCttExpress(payload, number);
-                } }]);
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, firstAttemptMs(remainingMs)) },
+            { id: 'retry', recovers: (error) => error instanceof CttExpressErrorReply || error instanceof UnreadableReply || isNetworkFailure(error),
+                run: ({ signal, remainingMs }) => read(signal, remainingMs) },
+        ]);
     }
 }
 export const adapter = (environment) => {
     const tracker = new CttExpressTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
-    return { id: 'ctt-express', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+    return { id: 'ctt-express', recordsSteps: true, steps: ['direct', 'retry'], track: (input, context) => tracker.fetch(input.number, context),
         recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCttExpressNumber(number))) };
 };

package/dist/carriers/ctt-express/parser.d.ts

@@ -1,3 +1,7 @@
+import { IndeterminateError } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
+/** A reply that carries an error in place of the shipment. */
+export declare class CttExpressErrorReply extends IndeterminateError {
+}
 export declare function normalizeCttExpressNumber(raw: string): string;
 export declare function parseCttExpress(payload: unknown, number: string): CarrierResult;

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

@@ -6,6 +6,9 @@ import { calendarDay, explicitOffsetTime } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyCttExpressStatus } from './status.js';
+/** A reply that carries an error in place of the shipment. */
+export class CttExpressErrorReply extends IndeterminateError {
+}
 export function normalizeCttExpressNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!isCttExpressTrackingNumber(number))
@@ -33,7 +36,7 @@ export function parseCttExpress(payload, number) {
     // An upstream Invalid token reply can precede successful anonymous retrieval.
     // No error signature has established a reliable parcel-negative response.
     if (payload.error != null)
-        throw new IndeterminateError('CTT Express', 'CTT Express returned an inconclusive tracking response');
+        throw new CttExpressErrorReply('CTT Express', 'CTT Express returned an inconclusive tracking response');
     const data = payload.data;
     if (!isRecord(data) || data.shipping_code !== requested || !isRecord(data.shipping_history)) {
         throw new SchemaError('CTT Express', 'CTT Express returned a different or incomplete shipment');

package/dist/carriers/parcelforce/carrier.json

@@ -18,7 +18,8 @@
     "mode": "automatic",
     "adapter": "royal-mail",
     "steps": [
-      "browser"
+      "browser",
+      "retry"
     ],
     "browser": true
   },

package/dist/carriers/royal-mail/adapter.js

@@ -13,6 +13,8 @@ const SETTLE_TIMEOUT_MS = 15_000;
 // A healthy lookup needs a fraction of this. A browser that is down fails every
 // parcel the same way, and each failure must not hold a consumer's run for a minute.
 const BROWSER_TIMEOUT_MS = 30_000;
+// A fresh consent flow and the separate history request need time to complete.
+const BROWSER_RETRY_MIN_MS = 15_000;
 const MAX_CAPTURED = 20;
 export class RoyalMailTracker {
     timeoutMs;
@@ -39,8 +41,17 @@ export class RoyalMailTracker {
     async fetch(trackingNumber, context = {}) {
         const number = normalizeRoyalMailNumber(trackingNumber);
         if (this.#browserWsEndpoint || this.#executablePath) {
-            return runSteps({ carrier: 'royal-mail', budgetMs: context.budgetMs ?? this.timeoutMs,
-                signal: context.signal, recorder: this.#recorder }, [{ id: 'browser', run: ({ remainingMs, signal }) => fetchRoyalMailInBrowser(number, this.#executablePath ?? '', signal, Math.min(BROWSER_TIMEOUT_MS, remainingMs), this.#fullHistory, this.#browserProxy, this.#browserWsEndpoint) }]);
+            const budgetMs = Math.min(BROWSER_TIMEOUT_MS, context.budgetMs ?? this.timeoutMs);
+            const started = performance.now();
+            const run = ({ remainingMs, signal }) => fetchRoyalMailInBrowser(number, this.#executablePath ?? '', signal, remainingMs, this.#fullHistory, this.#browserProxy, this.#browserWsEndpoint);
+            return runSteps({ carrier: 'royal-mail', budgetMs,
+                signal: context.signal, recorder: this.#recorder }, [
+                { id: 'browser', run },
+                // Each call disposes its context before returning. A fresh session can
+                // recover an intermittent edge refusal without retaining issued tokens.
+                { id: 'retry', run, recovers: error => error instanceof ChallengeError
+                        && budgetMs - (performance.now() - started) >= BROWSER_RETRY_MIN_MS },
+            ]);
         }
         // The legacy service remains available through explicit tracker instances.
         const trawl = this.#trawl;
@@ -171,7 +182,7 @@ export const adapter = environment => {
     const tracker = new RoyalMailTracker({ executablePath: environment.browserExecutablePath,
         browserWsEndpoint: endpoint, browserProxy: environment.env.ROYAL_MAIL_BROWSER_PROXY, recorder: environment.recorder, fullHistory: true });
     return {
-        id: 'royal-mail', recordsSteps: true, steps: ['browser'],
+        id: 'royal-mail', recordsSteps: true, steps: ['browser', 'retry'],
         track: (input, context) => {
             normalizeRoyalMailNumber(input.number);
             if (!endpoint && !environment.browserExecutablePath)

package/dist/carriers/royal-mail/carrier.json

@@ -16,7 +16,8 @@
     "mode": "automatic",
     "adapter": "royal-mail",
     "steps": [
-      "browser"
+      "browser",
+      "retry"
     ],
     "browserRecognition": {
       "rank": 910

package/dist/carriers/seur/parser.js

@@ -5,9 +5,10 @@ import { isRecord } from '../../core/types.js';
 import { classifySeurStatus } from './status.js';
 export function normalizeSeurNumber(raw) {
     const number = raw.replace(/\s/g, '');
-    // Twenty-two digits is a sender's reference, which the lookup also finds.
-    if (!/^(?:\d{7}|\d{14}|\d{21}|\d{22})$/.test(number))
-        throw new InvalidInputError('SEUR', 'SEUR requires a seven, fourteen, twenty-one or twenty-two digit identifier');
+    // Twenty-two digits is a sender's reference, which the lookup also finds, as
+    // it finds twelve digits a provider names SEUR for.
+    if (!/^(?:\d{7}|\d{12}|\d{14}|\d{21}|\d{22})$/.test(number))
+        throw new InvalidInputError('SEUR', 'SEUR requires a seven, twelve, fourteen, twenty-one or twenty-two digit identifier');
     return number;
 }
 /**

package/dist/carriers/seur/status.js

@@ -8,6 +8,8 @@ const observed = {
     LC003: { group: 'EN REPARTO', wording: 'EL ENVÍO ESTÁ EN REPARTO.', mapped: { status: 'out_for_delivery', stage: 'out_for_delivery' } },
     LI300: { group: 'EN DEMORA', wording: 'EL ENVÍO HA SUFRIDO UN RETRASO Y ES POSIBLE QUE SE DEMORE LA ENTREGA. DISCULPA LAS MOLESTIAS.', mapped: exception },
     LI582: { group: 'EN DEMORA', wording: 'EL ENVÍO HA SUFRIDO UN RETRASO PROVOCANDO UNA POSIBLE DEMORA EN LA ENTREGA. DISCULPA LAS MOLESTIAS.', mapped: exception },
+    // Recorded after the day's delivery round, which starts again the next day.
+    LI521: { group: 'EN INCIDENCIA', wording: 'EL ENVÍO NO SE HA ENTREGADO PORQUE LA DIRECCIÓN DE ENTREGA ESTÁ INCOMPLETA O ERRÓNEA.', mapped: { status: 'exception', stage: 'failed_attempt' } },
     LI523: { group: 'EN INCIDENCIA', wording: 'EL ENVÍO NO SE HA ENTREGADO POR AUSENCIA O CIERRE. SE PUEDE REPROGRAMAR UNA NUEVA ENTREGA.', mapped: { status: 'exception', stage: 'failed_attempt' } },
     LI524: { group: 'EN INCIDENCIA', wording: 'EL ENVÍO NO SE HA ENTREGADO PORQUE NO ES LA DIRECCIÓN ACTUAL DEL DESTINATARIO.', mapped: exception },
     LI530: { group: 'ENTREGA EN TIENDA', wording: 'EL ENVÍO ESTÁ DISPONIBLE PARA RECOGER EN EL PUNTO SEUR PICKUP.', mapped: { status: 'in_transit', stage: 'ready_for_pickup' } },

package/dist/carriers/seur/statuses.json

@@ -89,6 +89,15 @@
       "stage": "out_for_delivery",
       "confirmedBy": "live"
     },
+    {
+      "code": "LI521",
+      "wording": "EL ENVÍO NO SE HA ENTREGADO PORQUE LA DIRECCIÓN DE ENTREGA ESTÁ INCOMPLETA O ERRÓNEA.",
+      "language": "es",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-22",
+      "note": "Recorded hours after each day's delivery round, which starts again the next day: an attempt the address held up."
+    },
     {
       "code": "LI523",
       "wording": "EL ENVÍO NO SE HA ENTREGADO POR AUSENCIA O CIERRE. SE PUEDE REPROGRAMAR UNA NUEVA ENTREGA.",

package/dist/carriers/ups/adapter.d.ts

@@ -24,7 +24,7 @@ export declare class UPSUnavailableError extends IndeterminateError {
 }
 /**
  * The browser step, skipped while UPS's status call would likely answer HTTP 500
- * again: inconclusive, so another source may answer.
+ * again, or Akamai block the page again: inconclusive, so another source may answer.
  */
 export declare class UPSStatusHeldError extends IndeterminateError {
     readonly heldMs: number;

package/dist/carriers/ups/adapter.js

@@ -27,8 +27,10 @@ const SETTLE_TIMEOUT_MS = 15_000;
 const MAX_CAPTURED = 20;
 // UPS's status call answers HTTP 500 in bursts. During one, the browser's call failed again
 // for every lookup that followed within a minute and nearly every one within five, while
-// lookups after a longer pause were answered. After a 500 the browser rests that long, and
-// the caller's next source answers meanwhile.
+// lookups after a longer pause were answered. Akamai's blocks, which keep the browser on its
+// interstitial, come in bursts too: 84% of the lookups within five minutes of one were
+// blocked, against 3% otherwise. After either the browser rests that long, and the caller's
+// next source answers meanwhile.
 export const STATUS_HOLD_MS = 5 * 60_000;
 // Provider strings are short; the rendered page's whole text is not, and the
 // identity check reads all of it, so it passes its own limit to `clean`.
@@ -65,22 +67,41 @@ export class UPSUnavailableError extends IndeterminateError {
 }
 /**
  * The browser step, skipped while UPS's status call would likely answer HTTP 500
- * again: inconclusive, so another source may answer.
+ * again, or Akamai block the page again: inconclusive, so another source may answer.
  */
 export class UPSStatusHeldError extends IndeterminateError {
     heldMs;
     constructor(heldMs) {
-        super('UPS', `UPS's status call answered HTTP 500 moments ago; the browser waits ${Math.ceil(heldMs / 1_000)} s more`);
+        super('UPS', `UPS's tracking failed in the browser moments ago; the browser waits ${Math.ceil(heldMs / 1_000)} s more`);
         this.heldMs = heldMs;
         this.name = 'UPSStatusHeldError';
     }
 }
 /**
- * When the status call last answered HTTP 500, by browser service. Every
- * tracker in the process that uses the service shares it, as a host's several
- * registries do; a restart forgets it.
+ * When the status call last answered HTTP 500, or Akamai last blocked the
+ * page, by browser service. Every tracker in the process that uses the service
+ * shares it, as a host's several registries do; a restart forgets it.
  */
 const statusFailedAt = new Map();
+/**
+ * Whether the browser service's HTTP 500 says its last browser tier stayed
+ * blocked, as on Akamai's interstitial, until the tiers or the deadline ran
+ * out. An excerpt cut short still shows the status.
+ */
+function trawlBlocked(error) {
+    if (!(error instanceof UpstreamHttpError) || error.status !== 500)
+        return false;
+    const excerpt = error.diagnostics?.body_excerpt ?? '';
+    let reply;
+    try {
+        reply = JSON.parse(excerpt);
+    }
+    catch {
+        return /"status"\s*:\s*"blocked"/.test(excerpt);
+    }
+    const last = isRecord(reply) && Array.isArray(reply.timings) ? reply.timings.at(-1) : undefined;
+    return isRecord(last) && (last.tier === 2 || last.tier === 3) && last.status === 'blocked';
+}
 /** How long the browser service still rests after a 500, or 0. */
 function statusHeldMs(trawl) {
     const failedAt = statusFailedAt.get(trawl.endpoint.href);
@@ -579,21 +600,29 @@ export class UPSTracker {
      * validated in the page. The page the browser rendered is the last resort.
      */
     async #trawlResult(trawl, number, timeoutMs, signal) {
-        const page = await trawl.scrape({
-            url: upsTrackingUrl(number),
-            skipHttp: true,
-            maxTier: 3,
-            maxTimeout: timeoutMs,
-            captureResponses: [STATUS_API],
-            settleTimeout: SETTLE_TIMEOUT_MS,
-        }, {
-            provider: TRAWL_PROVIDER,
-            timeoutMs,
-            maxBytes: MAX_BYTES,
-            fetcher: this.#fetcher,
-            signal,
-            captureWindow: 'last',
-        });
+        let page;
+        try {
+            page = await trawl.scrape({
+                url: upsTrackingUrl(number),
+                skipHttp: true,
+                maxTier: 3,
+                maxTimeout: timeoutMs,
+                captureResponses: [STATUS_API],
+                settleTimeout: SETTLE_TIMEOUT_MS,
+            }, {
+                provider: TRAWL_PROVIDER,
+                timeoutMs,
+                maxBytes: MAX_BYTES,
+                fetcher: this.#fetcher,
+                signal,
+                captureWindow: 'last',
+            });
+        }
+        catch (error) {
+            if (trawlBlocked(error))
+                statusFailedAt.set(trawl.endpoint.href, Date.now());
+            throw error;
+        }
         // The last matching response is authoritative. An earlier success cannot
         // answer after the page's retry was refused or returned invalid data.
         const entry = page.capturedResponses.filter((capture) => capture.url === STATUS_API).slice(-MAX_CAPTURED).at(-1);

package/dist/carriers/wanbexpress/adapter.js

@@ -18,8 +18,10 @@ export class WanbTracker {
     }
     async direct(raw, context = {}) {
         const number = normalizeWanbNumber(raw);
+        // Node's fetch sends `Accept-Language: *` unless told otherwise, and the
+        // tracker fails on it with HTTP 500, often after several seconds.
         const { bytes } = await fetchBounded(`${API}?TrackingNumber=${number}`, { signal: context.signal,
-            headers: { Accept: 'application/json', 'User-Agent': userAgentOf(this.environment.userAgent) } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(context.budgetMs ?? 5000)), maxBytes: MAX_BYTES, fetcher: this.environment.fetcher });
+            headers: { Accept: 'application/json', 'Accept-Language': 'en', 'User-Agent': userAgentOf(this.environment.userAgent) } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(context.budgetMs ?? 5000)), maxBytes: MAX_BYTES, fetcher: this.environment.fetcher });
         return this.parse(decodeText(bytes), number);
     }
     parse(body, number) {

package/dist/providers/status.js

@@ -8,8 +8,8 @@
  * rules). A stage a provider declares and a UPU event code it maps are
  * `carrier_map`, so their scans never reach the app's review. Wording no rule
  * reads has no stage. Chronopost's notice to the recipient, a bare delivery
- * estimate and a note that the recipient's details changed, none of them a
- * scan, are left out on purpose.
+ * estimate, a note that the recipient's details changed and SEUR's delay
+ * notice, none of them a scan, are left out on purpose.
  */
 import { CHRONOPOST_NOTIFICATION } from '../carriers/chronopost/status.js';
 import { normalizeStatusWording } from '../core/status/statusMap.js';
@@ -29,5 +29,8 @@ export const statusMap = {
         }, {
             wording: 'recipient information updated',
             note: "A note that the recipient's details changed, after the local carrier's receipt: not a scan, so it keeps the stage the parcel already had.",
+        }, {
+            wording: 'en demora - el envío ha sufrido un retraso provocando una posible demora en la entrega.',
+            note: "SEUR's delay notice as Ship24 relays it, group before wording: not a scan, so it keeps the stage the parcel already had.",
         }],
 };

package/dist/server/openapi.json

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

package/package.json

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