universal-parcel-scraper 0.5.0-main.324 → 0.7.0-main.326

package/data/carrier.schema.json

@@ -172,6 +172,21 @@
         },
         "localClocks": {
           "type": "boolean"
+        },
+        "browserRecognition": {
+          "description": "Present when the adapter implements recognizeWithBrowser(): opt-in browser confirmation without recipient inputs, requiring dated shipment activity. Higher rank is asked first after HTTP checks are inconclusive.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rank"
+          ],
+          "properties": {
+            "rank": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
         }
       }
     },

package/data/catalog.json

@@ -469,7 +469,8 @@
     "tracking": {
       "mode": "automatic",
       "adapter": "dhl-ecommerce",
-      "recognitionRank": 23
+      "recognitionRank": 23,
+      "browserRecognitionRank": 90
     },
     "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
     "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -675,7 +676,8 @@
     "timezone": "UTC",
     "tracking": {
       "mode": "automatic",
-      "adapter": "fedex"
+      "adapter": "fedex",
+      "browserRecognitionRank": 100
     },
     "canaryUrl": "https://www.fedex.com/fedextrack/",
     "trackingUrlTemplate": "https://www.fedex.com/fedextrack/?trknbr={trackingNumber}",

package/dist/browser/scraper.js

@@ -480,7 +480,8 @@ var ue = {
 		tracking: {
 			mode: "automatic",
 			adapter: "dhl-ecommerce",
-			recognitionRank: 23
+			recognitionRank: 23,
+			browserRecognitionRank: 90
 		},
 		canaryUrl: "https://www.dhl.com/ch-en/home/tracking.html",
 		trackingUrlTemplate: "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -580,7 +581,8 @@ var ue = {
 		timezone: "UTC",
 		tracking: {
 			mode: "automatic",
-			adapter: "fedex"
+			adapter: "fedex",
+			browserRecognitionRank: 100
 		},
 		canaryUrl: "https://www.fedex.com/fedextrack/",
 		trackingUrlTemplate: "https://www.fedex.com/fedextrack/?trknbr={trackingNumber}",
@@ -3449,6 +3451,7 @@ var et = /* @__PURE__ */ new Set([
 	"exception",
 	"unknown"
 ]), tt = new Set(fe), nt = [
+	"current_stage_source",
 	"last_status_text",
 	"last_update",
 	"expected_delivery",
@@ -3465,7 +3468,8 @@ var et = /* @__PURE__ */ new Set([
 	"time",
 	"location",
 	"description",
-	"stage"
+	"stage",
+	"stage_source"
 ];
 function it(e, t) {
 	let n = (e) => typeof e == "string" && e.trim() ? Number(e) : e, r = n(e), i = n(t);
@@ -7381,8 +7385,8 @@ function ko(e, t = "in_transit") {
 function Ao(e, t = "in_transit") {
 	return ko(e, t).stage;
 }
-function jo(e, t) {
-	return Eo.has(e) ? "carrier_map" : ko(t).source;
+function jo(e, t, n) {
+	return Eo.has(e) ? typeof n == "string" && n.length <= 100 && (n === "none" || n === "carrier_map" || /^wording:[a-z0-9_]+$/.test(n)) ? n : "carrier_map" : ko(t).source;
 }
 function Mo(e) {
 	let t = at(e), n = Do(t), r = (t.events ?? []).map((e) => {
@@ -7390,7 +7394,7 @@ function Mo(e) {
 		return {
 			...e,
 			stage: t ?? n.stage,
-			stage_source: t ? "carrier_map" : n.source,
+			stage_source: t ? jo(t, e.description ?? "", e.stage_source) : n.source,
 			instant: $a(e.time)?.iso ?? null
 		};
 	});
@@ -7465,46 +7469,54 @@ function zo(e, t = {}) {
 			carrier: t,
 			preferred: r.preferred === !0
 		}] : [];
-	}) : [], o = r ? a.map(({ carrier: e }) => e) : n.candidates, s = r ? a.filter((e) => e.preferred).map(({ carrier: e }) => e) : n.preferred, c = new Set(s.filter((e) => Lo[e] === void 0).map((e) => Io(e)).filter(Boolean)), l = (e) => [
+	}) : [], o = r ? a.map(({ carrier: e }) => e) : n.candidates, s = r ? a.filter((e) => e.preferred).map(({ carrier: e }) => e) : n.preferred, c = t.phase === "browser" ? Object.fromEntries(Object.entries(_).map(([e, t]) => [e, t.tracking.browserRecognitionRank])) : Lo, l = new Set(s.filter((e) => c[e] === void 0).map((e) => Io(e)).filter(Boolean)), u = (e) => [
 		+(e === t.hint),
 		+!!s.includes(e),
-		Lo[e] ?? 0
+		c[e] ?? 0
 	];
-	return o.filter((e) => Lo[e] !== void 0 && we.has(e) && xe(e) !== "universal" && !c.has(Io(e)) && !t.skip?.(e)).map((e) => ({
+	return o.filter((e) => c[e] !== void 0 && we.has(e) && xe(e) !== "universal" && !l.has(Io(e)) && !t.skip?.(e)).map((e) => ({
 		carrier: e,
-		score: l(e)
+		score: u(e)
 	})).sort((e, t) => t.score[0] - e.score[0] || t.score[1] - e.score[1] || t.score[2] - e.score[2]).map(({ carrier: t }) => ({
 		carrier: t,
 		needsInput: Ce(t, e)[0]?.field ?? null,
 		preferred: s.includes(t)
-	}));
+	})).filter((e) => t.phase !== "browser" || !e.needsInput);
 }
 //#endregion
 //#region core/recognition/index.ts
 var Bo = 5184e6;
-async function Vo(e, t, n) {
-	let r = e.map((e) => ({
+async function Vo(e, t, n, r) {
+	let i = e.map((e) => ({
 		...e,
 		status: "failed",
 		lastActivityAt: null
-	})), i, a = new Promise((e) => {
-		i = setTimeout(e, n);
-	}), o = e.map(async (e, n) => {
+	}));
+	if (r?.throwIfAborted(), n <= 0 || e.length === 0) return i;
+	let a = new AbortController(), o = {
+		signal: a.signal,
+		budgetMs: n
+	}, s, c = () => void 0, l = new Promise((e) => {
+		c = () => {
+			a.abort(), e();
+		}, s = setTimeout(c, n), r?.addEventListener("abort", c, { once: !0 });
+	}), u = e.map(async (e, n) => {
 		try {
-			let i = await t(e.carrier);
-			r[n] = {
+			let r = await t(e.carrier, o);
+			if (a.signal.aborted) return;
+			i[n] = {
 				...e,
-				status: i.known ? "known" : "unknown",
-				lastActivityAt: i.lastActivityAt ?? null
+				status: r.known ? "known" : "unknown",
+				lastActivityAt: r.lastActivityAt ?? null
 			};
 		} catch {}
 	});
 	try {
-		await Promise.race([Promise.all(o), a]);
+		await Promise.race([Promise.all(u), l]);
 	} finally {
-		clearTimeout(i);
+		clearTimeout(s), r?.removeEventListener("abort", c);
 	}
-	return r.map((e) => ({ ...e }));
+	return r?.throwIfAborted(), i.map((e) => ({ ...e }));
 }
 function Ho(e, t) {
 	let n = Date.parse(e.lastActivityAt ?? "");

package/dist/carriers/canada-post/adapter.d.ts

@@ -18,6 +18,7 @@ export declare class CanadaPostTracker {
         canonical_tracking_number?: string;
         status?: import("../../index.js").CarrierStatus;
         current_stage?: string;
+        current_stage_source?: string;
         last_status_text?: string | null;
         last_update?: string | null;
         expected_delivery?: string | null;

package/dist/carriers/dhl-ecommerce/adapter.d.ts

@@ -48,5 +48,6 @@ export declare class DHLEcommerceTracker {
     recognize(trackingNumber: string, context?: TrackingContext): Promise<Recognition>;
     private direct;
     private browser;
+    recognizeWithBrowser(number: string, context?: TrackingContext, previousError?: unknown): Promise<import("../../core/adapter/index.js").BrowserRecognition>;
 }
 export declare const adapter: AdapterFactory;

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

@@ -7,7 +7,7 @@
  * accepted, and the id itself is never retained.
  */
 import { DateTime } from 'luxon';
-import { accepted, lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
+import { accepted, lookupBudget, recognizeFromBrowserLookup, recognizeFromLookup } from '../../core/adapter/index.js';
 import { ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { runSteps, singleFlight, takeTurn } from '../../core/runner/index.js';
 import { countryTimeZone } from '../../core/time/index.js';
@@ -22,6 +22,11 @@ const WEBTRACK_API = 'https://api.dhlecs.com/webtrack/v4/tracking';
 const DIRECT_TIMEOUT_MS = 15_000;
 /** Statuses DHL answers with while its challenge is unsolved. */
 const CHALLENGE_STATUSES = [401, 403, 419, 428];
+function browserRecoveryAllowed(error) {
+    return error instanceof ChallengeError || error instanceof UpstreamNetworkError
+        || error instanceof UpstreamHttpError && error.status >= 500
+        || error instanceof IndeterminateError && ['webtrack_not_found', 'webtrack_no_history'].includes(error.reason ?? '');
+}
 /**
  * UTAPI strings occasionally carry markup. Tags are dropped without a
  * separator, as this adapter has always done, before the shared cleaner
@@ -222,9 +227,7 @@ export class DHLEcommerceTracker {
         const timeoutMs = this.options.timeoutMs ?? 45_000;
         return takeTurn(this.serialize, PROVIDER, context, ({ signal, budgetMs }) => runSteps({ carrier: 'dhl-ecommerce', budgetMs: budgetMs ?? this.options.budgetMs ?? timeoutMs + 15_000, signal, recorder: this.recorder }, [
             { id: 'direct', run: (step) => this.direct(number, Math.min(DIRECT_TIMEOUT_MS, step.remainingMs), step.signal) },
-            { id: 'browser', recovers: (error) => error instanceof ChallengeError || error instanceof UpstreamNetworkError
-                    || error instanceof UpstreamHttpError && error.status >= 500
-                    || error instanceof IndeterminateError && ['webtrack_not_found', 'webtrack_no_history'].includes(error.reason ?? ''),
+            { id: 'browser', recovers: browserRecoveryAllowed,
                 run: (step) => this.browser(number, Math.max(1, Math.floor(Math.min(timeoutMs, step.remainingMs))), step.signal) },
         ]));
     }
@@ -277,6 +280,13 @@ export class DHLEcommerceTracker {
             throw error;
         }
     }
+    async recognizeWithBrowser(number, context = {}, previousError) {
+        if (previousError !== undefined && !browserRecoveryAllowed(previousError)) {
+            throw previousError instanceof Error ? previousError : new Error('DHL eCommerce HTTP recognition cannot recover through a browser');
+        }
+        const normalized = normalizeDHLEcommerceNumber(number);
+        return takeTurn(this.serialize, PROVIDER, context, (step) => recognizeFromBrowserLookup(() => runSteps({ carrier: 'dhl-ecommerce', budgetMs: step.budgetMs ?? 20_000, signal: step.signal, recorder: this.recorder }, [{ id: 'browser', run: ({ signal, remainingMs }) => this.browser(normalized, remainingMs, signal) }])));
+    }
 }
 export const adapter = (environment) => {
     const tracker = new DHLEcommerceTracker({
@@ -288,5 +298,6 @@ export const adapter = (environment) => {
         steps: ['direct', 'browser'],
         track: (input, context) => tracker.fetch(input.number, context),
         recognize: (number, context) => tracker.recognize(number, context),
+        recognizeWithBrowser: (number, context, previousError) => tracker.recognizeWithBrowser(number, context, previousError),
     };
 };

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

@@ -26,6 +26,9 @@
     ],
     "recognition": {
       "rank": 23
+    },
+    "browserRecognition": {
+      "rank": 90
     }
   },
   "capabilities": [

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

@@ -1,4 +1,4 @@
-import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
 import { TrawlClient } from '../../core/transport/index.js';

package/dist/carriers/fedex/adapter.js

@@ -1,4 +1,5 @@
 import { load } from 'cheerio';
+import { recognizeFromBrowserLookup } from '../../core/adapter/index.js';
 import { ChallengeError, InputRequiredError, InvalidInputError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError, } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
@@ -310,5 +311,6 @@ export const adapter = (environment) => {
         // Browser-backed direct tracking; universal recovery belongs to the caller.
         steps: ['trawl'],
         track: (input, context) => tracker.fetch(input.number, context),
+        recognizeWithBrowser: (number, context) => recognizeFromBrowserLookup(() => tracker.fetch(number, context)),
     };
 };

package/dist/carriers/fedex/carrier.json

@@ -15,7 +15,10 @@
     "adapter": "fedex",
     "steps": [
       "trawl"
-    ]
+    ],
+    "browserRecognition": {
+      "rank": 100
+    }
   },
   "capabilities": [
     "history",

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

@@ -57,6 +57,10 @@ export interface Recognition {
     /** The newest activity the check saw, when it reports one; old parcels can share a reused number. */
     lastActivityAt?: string | null;
 }
+/** Browser confirmation retains the lookup so a consumer can reuse its history. */
+export interface BrowserRecognition extends Recognition {
+    result?: CarrierResult;
+}
 export interface CarrierAdapter {
     readonly id: string;
     /** The tiers this adapter can go through, in order; telemetry labels use these ids. */
@@ -71,6 +75,8 @@ export interface CarrierAdapter {
      * other failure throws.
      */
     recognize?(number: string, context?: TrackingContext): Promise<Recognition>;
+    /** Opt-in confirmation through the adapter's browser path, without recipient inputs. */
+    recognizeWithBrowser?(number: string, context?: TrackingContext, previousError?: unknown): Promise<BrowserRecognition>;
 }
 export type AdapterFactory = (environment: AdapterEnvironment) => CarrierAdapter;
 /**
@@ -83,6 +89,8 @@ export type AdapterFactory = (environment: AdapterEnvironment) => CarrierAdapter
 /** Whether a number check passes: false when it rejects the number. */
 export declare function accepted(check: () => unknown): boolean;
 export declare function recognizeFromLookup(lookup: () => Promise<CarrierResult>, accepts?: () => boolean): Promise<Recognition>;
+/** Browser shells and undated default statuses do not establish a shipment. */
+export declare function recognizeFromBrowserLookup(lookup: () => Promise<CarrierResult>): Promise<BrowserRecognition>;
 /** Registered adapter factories plus the carrier → adapter mapping, as generated. */
 export interface RegistryDefinition {
     factories: Readonly<Record<string, AdapterFactory>>;

package/dist/core/adapter/index.js

@@ -84,6 +84,14 @@ export async function recognizeFromLookup(lookup, accepts = () => true) {
             : Number.isFinite(updated) ? new Date(updated).toISOString() : null,
     };
 }
+/** Browser shells and undated default statuses do not establish a shipment. */
+export async function recognizeFromBrowserLookup(lookup) {
+    let result;
+    const answer = await recognizeFromLookup(async () => (result = await lookup()));
+    if (!answer.known || !answer.lastActivityAt || !result)
+        return { known: false, lastActivityAt: null };
+    return { ...answer, result };
+}
 /**
  * One adapter instance per adapter id for the process lifetime, created on
  * first use so a broken provider module cannot prevent unrelated carriers

package/dist/core/catalog/recognition.d.ts

@@ -11,13 +11,14 @@ export interface RecognitionCandidate {
 /**
  * The low-confidence candidates worth asking, best first: the carrier a
  * universal provider named, then the ones number evidence backs, then the
- * catalog's popularity rank. Only carriers that declare `tracking.recognition`
- * qualify. A high-confidence dedicated carrier needs no recognition; the
+ * catalog's popularity rank. HTTP is the default; `phase: 'browser'` selects
+ * the separate opt-in browser catalog. A high-confidence dedicated carrier needs no recognition; the
  * unknown postal carrier still needs a direct carrier to confirm it.
  */
 export declare function recognitionCandidates(number: string, options?: {
     hint?: string;
     skip?: (carrier: string) => boolean;
+    phase?: 'http' | 'browser';
 }): RecognitionCandidate[];
 /** The carriers the detect route asks about a number, best first; empty when none can answer. */
 export declare function recognitionAskedCarriers(number: string): string[];

package/dist/core/catalog/recognition.js

@@ -17,8 +17,8 @@ export const MAX_RECOGNITIONS = 5;
 /**
  * The low-confidence candidates worth asking, best first: the carrier a
  * universal provider named, then the ones number evidence backs, then the
- * catalog's popularity rank. Only carriers that declare `tracking.recognition`
- * qualify. A high-confidence dedicated carrier needs no recognition; the
+ * catalog's popularity rank. HTTP is the default; `phase: 'browser'` selects
+ * the separate opt-in browser catalog. A high-confidence dedicated carrier needs no recognition; the
  * unknown postal carrier still needs a direct carrier to confirm it.
  */
 export function recognitionCandidates(number, options = {}) {
@@ -43,19 +43,22 @@ export function recognitionCandidates(number, options = {}) {
     const candidates = unknownPostalCarrier ? postalMatches.map(({ carrier }) => carrier) : detected.candidates;
     const preferred = unknownPostalCarrier
         ? postalMatches.filter((match) => match.preferred).map(({ carrier }) => carrier) : detected.preferred;
+    const ranks = options.phase === 'browser'
+        ? Object.fromEntries(Object.entries(CARRIER_DEFINITIONS).map(([id, definition]) => [id, definition.tracking.browserRecognitionRank]))
+        : CARRIER_RECOGNITION_RANKS;
     // A carrier the number points to but that cannot be asked (DPD France) keeps
     // its brand's other networks out: DPD's guest API also answers for DPD
     // France parcels, and would file one under DPD Switzerland.
     const shadowed = new Set(preferred
-        .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] === undefined)
+        .filter((carrier) => ranks[carrier] === undefined)
         .map((carrier) => carrierBrand(carrier)).filter(Boolean));
     const score = (carrier) => [
         carrier === options.hint ? 1 : 0,
         preferred.includes(carrier) ? 1 : 0,
-        CARRIER_RECOGNITION_RANKS[carrier] ?? 0,
+        ranks[carrier] ?? 0,
     ];
     return candidates
-        .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] !== undefined && AUTOMATIC_CARRIER_IDS.has(carrier)
+        .filter((carrier) => ranks[carrier] !== undefined && AUTOMATIC_CARRIER_IDS.has(carrier)
         && carrierAdapter(carrier) !== 'universal' && !shadowed.has(carrierBrand(carrier)) && !options.skip?.(carrier))
         .map((carrier) => ({ carrier, score: score(carrier) }))
         // Array#sort is stable: equal scores keep the catalog order.
@@ -64,7 +67,7 @@ export function recognitionCandidates(number, options = {}) {
         carrier,
         needsInput: requiredRequirements(carrier, number)[0]?.field ?? null,
         preferred: preferred.includes(carrier),
-    }));
+    })).filter((candidate) => options.phase !== 'browser' || !candidate.needsInput);
 }
 /** The carriers the detect route asks about a number, best first; empty when none can answer. */
 export function recognitionAskedCarriers(number) {

package/dist/core/catalog/types.d.ts

@@ -95,6 +95,8 @@ export interface CarrierDefinition {
         requirements?: readonly CarrierCatalogRequirement[];
         /** Present when the adapter can recognize a number; higher is asked first. */
         recognitionRank?: number;
+        /** Opt-in browser confirmation; higher is asked first after HTTP is inconclusive. */
+        browserRecognitionRank?: number;
         refresh?: {
             minMinutes: number;
             afterFailureMinutes?: number;

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

@@ -1,4 +1,4 @@
-import type { Recognition } from '../adapter/index.js';
+import type { Recognition, TrackingContext } from '../adapter/index.js';
 import type { RecognitionCandidate } from '../catalog/recognition.js';
 export { MAX_RECOGNITIONS, recognitionCandidates, type RecognitionCandidate, } from '../catalog/recognition.js';
 export type RecognitionStatus = 'known' | 'unknown' | 'failed';
@@ -8,10 +8,10 @@ export interface RecognitionOutcome extends RecognitionCandidate {
 }
 /**
  * Ask every candidate at once. A candidate that throws, or has not answered
- * when the budget runs out, is `failed`; its lookup may still finish in the
- * background, but its answer is ignored.
+ * when the budget runs out, is `failed`. The callback receives the deadline
+ * and cancellation signal; answers after either are ignored.
  */
-export declare function recognizeAll(candidates: readonly RecognitionCandidate[], recognize: (carrier: string) => Promise<Recognition>, budgetMs: number): Promise<RecognitionOutcome[]>;
+export declare function recognizeAll(candidates: readonly RecognitionCandidate[], recognize: (carrier: string, context: TrackingContext) => Promise<Recognition>, budgetMs: number, signal?: AbortSignal): Promise<RecognitionOutcome[]>;
 /**
  * The carrier the answers settle on: the only recent one, else the only one
  * number evidence backs, else, when every answer comes from one brand's

package/dist/core/recognition/index.js

@@ -14,16 +14,28 @@ export { MAX_RECOGNITIONS, recognitionCandidates, } from '../catalog/recognition
 const RECENT_ACTIVITY_MS = 60 * 24 * 3_600_000;
 /**
  * Ask every candidate at once. A candidate that throws, or has not answered
- * when the budget runs out, is `failed`; its lookup may still finish in the
- * background, but its answer is ignored.
+ * when the budget runs out, is `failed`. The callback receives the deadline
+ * and cancellation signal; answers after either are ignored.
  */
-export async function recognizeAll(candidates, recognize, budgetMs) {
+export async function recognizeAll(candidates, recognize, budgetMs, signal) {
     const outcomes = candidates.map((candidate) => ({ ...candidate, status: 'failed', lastActivityAt: null }));
+    signal?.throwIfAborted();
+    if (budgetMs <= 0 || candidates.length === 0)
+        return outcomes;
+    const controller = new AbortController();
+    const context = { signal: controller.signal, budgetMs };
     let timer;
-    const deadline = new Promise((resolve) => { timer = setTimeout(resolve, budgetMs); });
+    let stop = () => undefined;
+    const deadline = new Promise((resolve) => {
+        stop = () => { controller.abort(); resolve(); };
+        timer = setTimeout(stop, budgetMs);
+        signal?.addEventListener('abort', stop, { once: true });
+    });
     const asked = candidates.map(async (candidate, index) => {
         try {
-            const answer = await recognize(candidate.carrier);
+            const answer = await recognize(candidate.carrier, context);
+            if (controller.signal.aborted)
+                return;
             outcomes[index] = { ...candidate, status: answer.known ? 'known' : 'unknown', lastActivityAt: answer.lastActivityAt ?? null };
         }
         catch {
@@ -35,7 +47,9 @@ export async function recognizeAll(candidates, recognize, budgetMs) {
     }
     finally {
         clearTimeout(timer);
+        signal?.removeEventListener('abort', stop);
     }
+    signal?.throwIfAborted();
     return outcomes.map((outcome) => ({ ...outcome }));
 }
 function recent(outcome, now) {

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

@@ -15,6 +15,8 @@ export interface CarrierEvent extends JsonObject {
     location?: string;
     description?: string;
     stage?: string;
+    /** Explicit map, wording rule, or unresolved fallback used by the adapter. */
+    stage_source?: string;
     provider_code?: string;
     /**
      * Where the carrier itself puts the scanning facility, when it says so. The
@@ -29,6 +31,8 @@ export interface EventPoint extends JsonObject {
 export interface CarrierResult extends JsonObject {
     status?: CarrierStatus;
     current_stage?: string;
+    /** How the adapter chose current_stage, when it records that decision. */
+    current_stage_source?: string;
     last_status_text?: string | null;
     last_update?: string | null;
     expected_delivery?: string | null;

package/dist/core/result/index.js

@@ -20,6 +20,7 @@ const STATUSES = new Set([
 ]);
 const CURRENT_STAGES = new Set(STAGES);
 const OPTIONAL_TEXT_FIELDS = [
+    'current_stage_source',
     'last_status_text',
     'last_update',
     'expected_delivery',
@@ -33,7 +34,7 @@ const OPTIONAL_TEXT_FIELDS = [
     'international_tracking_number',
     'timezone',
 ];
-const EVENT_TEXT_FIELDS = ['time', 'location', 'description', 'stage'];
+const EVENT_TEXT_FIELDS = ['time', 'location', 'description', 'stage', 'stage_source'];
 /** A carrier's coordinates for a scan, or null when they are not a usable point. */
 export function eventPoint(latitude, longitude) {
     const number = (value) => typeof value === 'string' && value.trim() ? Number(value) : value;

package/dist/core/result/resolve.d.ts

@@ -4,7 +4,7 @@ export declare function resultStage(result: CarrierResult): Stage | null;
 export declare function resultHasUpdate(result: CarrierResult): boolean;
 export declare function classifyStage(text: string, fallback?: string): import("../status/wording.js").ClassifiedWording;
 export declare function inferStage(text: string, fallback?: string): string;
-export declare function stageSource(declaredStage: string, description: string): string;
+export declare function stageSource(declaredStage: string, description: string, source?: unknown): string;
 export interface ResolvedEvent extends CarrierEvent {
     stage: Stage;
     stage_source: string;

package/dist/core/result/resolve.js

@@ -31,8 +31,13 @@ export function classifyStage(text, fallback = 'in_transit') {
 export function inferStage(text, fallback = 'in_transit') {
     return classifyStage(text, fallback).stage;
 }
-export function stageSource(declaredStage, description) {
-    return stages.has(declaredStage) ? 'carrier_map' : classifyStage(description).source;
+export function stageSource(declaredStage, description, source) {
+    if (!stages.has(declaredStage))
+        return classifyStage(description).source;
+    if (typeof source === 'string' && source.length <= 100
+        && (source === 'none' || source === 'carrier_map' || /^wording:[a-z0-9_]+$/.test(source)))
+        return source;
+    return 'carrier_map';
 }
 /** Classify wording and expose verified instants while retaining the feed's clocks. */
 export function resolveResult(input) {
@@ -42,7 +47,7 @@ export function resolveResult(input) {
         const declared = stages.has(event.stage ?? '') ? event.stage : undefined;
         const classified = classifyWording(event.description ?? '', 'in_transit');
         return { ...event, stage: declared ?? classified.stage,
-            stage_source: declared ? 'carrier_map' : classified.source,
+            stage_source: declared ? stageSource(declared, event.description ?? '', event.stage_source) : classified.source,
             instant: explicitOffsetTime(event.time)?.iso ?? null };
     });
     return { ...result, ...(current ? { current_stage: current } : {}), events };

package/dist/data/catalog.json

@@ -469,7 +469,8 @@
         "tracking": {
             "mode": "automatic",
             "adapter": "dhl-ecommerce",
-            "recognitionRank": 23
+            "recognitionRank": 23,
+            "browserRecognitionRank": 90
         },
         "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
         "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -675,7 +676,8 @@
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "fedex"
+            "adapter": "fedex",
+            "browserRecognitionRank": 100
         },
         "canaryUrl": "https://www.fedex.com/fedextrack/",
         "trackingUrlTemplate": "https://www.fedex.com/fedextrack/?trknbr={trackingNumber}",

package/dist/generated/catalog.d.ts

@@ -309,6 +309,7 @@ export declare const CARRIER_CATALOG: {
             readonly mode: "automatic";
             readonly adapter: "dhl-ecommerce";
             readonly recognitionRank: 23;
+            readonly browserRecognitionRank: 90;
         };
         readonly canaryUrl: "https://www.dhl.com/ch-en/home/tracking.html";
         readonly trackingUrlTemplate: "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1";
@@ -398,6 +399,7 @@ export declare const CARRIER_CATALOG: {
         readonly tracking: {
             readonly mode: "automatic";
             readonly adapter: "fedex";
+            readonly browserRecognitionRank: 100;
         };
         readonly canaryUrl: "https://www.fedex.com/fedextrack/";
         readonly trackingUrlTemplate: "https://www.fedex.com/fedextrack/?trknbr={trackingNumber}";

package/dist/generated/catalog.js

@@ -470,7 +470,8 @@ export const CARRIER_CATALOG = {
         "tracking": {
             "mode": "automatic",
             "adapter": "dhl-ecommerce",
-            "recognitionRank": 23
+            "recognitionRank": 23,
+            "browserRecognitionRank": 90
         },
         "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
         "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -676,7 +677,8 @@ export const CARRIER_CATALOG = {
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "fedex"
+            "adapter": "fedex",
+            "browserRecognitionRank": 100
         },
         "canaryUrl": "https://www.fedex.com/fedextrack/",
         "trackingUrlTemplate": "https://www.fedex.com/fedextrack/?trknbr={trackingNumber}",

package/dist/providers/parcelsapp/adapter.js

@@ -225,7 +225,7 @@ function parseHistory(payload, trackingNumber, timezone = null) {
             scanCarriers.add(name);
         }
         if (parsed && scan)
-            scans.push({ event: Object.assign(parsed, { stage: scan.stage }), scan });
+            scans.push({ event: Object.assign(parsed, { stage: scan.stage, stage_source: 'carrier_map' }), scan });
     }
     markReturnLeg(scans);
     if (!events.length) {
@@ -314,7 +314,7 @@ export function parseParcelsAppHtml(html, trackingNumber, timezone = null) {
         if (parsed)
             events.push(parsed);
         if (parsed && scan)
-            scans.push({ event: Object.assign(parsed, { stage: scan.stage }), scan });
+            scans.push({ event: Object.assign(parsed, { stage: scan.stage, stage_source: 'carrier_map' }), scan });
     });
     markReturnLeg(scans);
     return { ...result(events, SOURCE), ...(undated ? { undated_event_count: undated } : {}),

package/dist/providers/postal-ninja/adapter.js

@@ -14,7 +14,7 @@ import { runSteps } from '../../core/runner/index.js';
 import { scrapeUniversalPage } from '../../core/transport/browser.js';
 import { isRecord } from '../../core/types.js';
 import { capturedBodies, captureFailure, loadCapture } from '../shared/capture.js';
-import { event, eventStage, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
+import { classifyEvent, event, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
 const SOURCE = 'Postal Ninja';
 const GET_API = 'https://postal.ninja/track/get';
 const CHECK_API = 'https://postal.ninja/track/check';
@@ -73,10 +73,11 @@ export function parsePostalNinjaResponse(payload, trackingNumber) {
                 events.push(parsed);
         }
         else {
-            const stage = eventStage(description) ?? 'pending';
+            const classified = classifyEvent(description);
+            const { stage } = classified;
             if (stage !== 'delivered' && hasPrivateDeliveryDetails(description))
                 continue;
-            events.push({ local_time: raw.dt, description: stage === 'delivered' ? 'Delivered' : description, stage });
+            events.push({ local_time: raw.dt, description: stage === 'delivered' ? 'Delivered' : description, ...classified });
         }
     }
     return result(events, SOURCE, true);

package/dist/providers/shared/result.d.ts

@@ -6,6 +6,11 @@ export declare function text(value: unknown): string;
 export declare function isNotice(description: string): boolean;
 export declare function hasPrivateDeliveryDetails(description: string): boolean;
 export declare function eventStage(description: string): Stage | undefined;
+/** Retain the decision before delivery wording is redacted or a stage is projected. */
+export declare function classifyEvent(description: string, declared?: Stage): {
+    stage: Stage;
+    stage_source: string;
+};
 export declare function event(time: unknown, description: unknown, stage?: unknown): CarrierEvent | null;
 /**
  * Like event(), but a scan without an offset keeps its wall time as local_time

package/dist/providers/shared/result.js

@@ -6,8 +6,7 @@
  *
  * The wording -> stage logic below is provider vocabulary (Ship24, ParcelsApp,
  * 17TRACK and Postal Ninja all render the same aggregated scans), not a
- * carrier status map. It is kept here unchanged while the classifiers are
- * merged in a later step.
+ * carrier status map. Its decisions retain their wording-rule provenance.
  */
 import { DateTime } from 'luxon';
 import { trackingLanguageStage } from '../../core/status/index.js';
@@ -99,7 +98,21 @@ function sourceEventStage(description, includeBroadMovement = true) {
     return undefined;
 }
 export function eventStage(description) {
-    return sourceEventStage(description, false) ?? trackingLanguageStage(description) ?? sourceEventStage(description);
+    const classified = classifyEvent(description);
+    return classified.stage_source === 'none' ? undefined : classified.stage;
+}
+/** Retain the decision before delivery wording is redacted or a stage is projected. */
+export function classifyEvent(description, declared) {
+    const specific = sourceEventStage(description, false);
+    if (specific)
+        return { stage: specific, stage_source: 'wording:provider' };
+    if (declared)
+        return { stage: declared, stage_source: 'carrier_map' };
+    const translated = trackingLanguageStage(description);
+    if (translated)
+        return { stage: translated, stage_source: 'wording:language' };
+    const broad = sourceEventStage(description);
+    return { stage: broad ?? 'pending', stage_source: broad ? 'wording:provider' : 'none' };
 }
 const EXPLICIT_OFFSET = /(?:Z|[+-]\d{2}:\d{2})$/;
 const LOCAL_WALL_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
@@ -110,11 +123,11 @@ function describe(description, stage) {
     const declared = typeof stage === 'string' && Object.hasOwn(STAGES, stage) ? STAGES[stage] : undefined;
     // Established source semantics (e.g. handoff/negation) remain first. A real
     // provider stage outranks the new intuitive translation fallback.
-    const resolved = sourceEventStage(label, false) ?? declared ?? trackingLanguageStage(label) ?? sourceEventStage(label);
-    if (resolved !== 'delivered' && hasPrivateDeliveryDetails(label))
+    const classified = classifyEvent(label, declared);
+    if (classified.stage !== 'delivered' && hasPrivateDeliveryDetails(label))
         return null;
     // Delivery descriptions can include signatures, access codes or door numbers.
-    return { description: resolved === 'delivered' ? 'Delivered' : label, stage: resolved ?? 'pending' };
+    return { description: classified.stage === 'delivered' ? 'Delivered' : label, ...classified };
 }
 export function event(time, description, stage) {
     const described = describe(description, stage);
@@ -155,14 +168,16 @@ export function result(events, source, preserveOrder = false) {
     // A well-formed reply with no scan left after notices and private details proves nothing about the parcel.
     if (!unique.length)
         throw new IndeterminateError(source, 'No usable tracking events');
-    const current = unique.find((e) => e.stage && e.stage !== 'pending')?.stage;
+    const currentEvent = unique.find((e) => e.stage && e.stage !== 'pending');
+    const current = currentEvent?.stage;
     // Unknown wording can be displayed, but must not imply movement.
     const status = current === 'delivered' ? 'delivered'
         : current === 'registered' || !current ? 'pending'
             : current === 'out_for_delivery' || current === 'ready_for_pickup' ? 'out_for_delivery'
                 : ['returned', 'failed_attempt', 'exception'].includes(current) ? 'exception' : 'in_transit';
     return {
-        status, current_stage: current ?? 'pending', last_status_text: unique[0].description,
+        status, current_stage: current ?? 'pending', current_stage_source: currentEvent?.stage_source ?? 'none',
+        last_status_text: unique[0].description,
         last_update: unique[0].time ?? null, expected_delivery: null, timezone: 'UTC',
         tracking_provider: source, events: unique,
     };

package/dist/providers/upu/adapter.js

@@ -4,7 +4,7 @@ import { InvalidInputError, NotFoundError, SchemaError } from '../../core/errors
 import { runSteps } from '../../core/runner/index.js';
 import { decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
-import { eventStage, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
+import { classifyEvent, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
 const SOURCE = 'UPU';
 export const UPU_BUDGET_MS = 8_000;
 const MAX_EVENTS = 1_000;
@@ -58,12 +58,14 @@ export function parseUpuResponse(payload, trackingNumber) {
             continue;
         if (!description || isNotice(description))
             throw new SchemaError(SOURCE, 'UPU returned no event label');
-        const stage = STAGES[raw.EventCd] ?? eventStage(description) ?? 'pending';
+        const mapped = STAGES[raw.EventCd];
+        const classified = mapped ? { stage: mapped, stage_source: 'carrier_map' } : classifyEvent(description);
+        const { stage } = classified;
         if (stage !== 'delivered' && hasPrivateDeliveryDetails(description))
             continue;
         const location = text(raw.EventLocation);
         events.push({ local_time: localTime(raw.EventDT), provider_code: raw.EventCd,
-            description: stage === 'delivered' ? 'Delivered' : description, stage,
+            description: stage === 'delivered' ? 'Delivered' : description, ...classified,
             ...(location && !hasPrivateDeliveryDetails(location) ? { location } : {}),
         });
     }

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.5.0"
+    "version": "0.7.0"
   },
   "paths": {
     "/health": {
@@ -691,6 +691,9 @@
           "current_stage": {
             "type": "string"
           },
+          "current_stage_source": {
+            "type": "string"
+          },
           "last_status_text": {
             "type": [
               "string",

package/package.json

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