universal-parcel-scraper 0.71.0-main.912 → 0.72.0-main.916

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **122 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **125 dedicated adapters** and **5 universal fallbacks**
 
 <sub>207 catalog entries · 66 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 3,381 such statuses, each filed under one stage.
+The carrier folders record 3,501 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/catalog.json

@@ -6069,7 +6069,9 @@
     "timezone": "Europe/Bucharest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "fan-courier",
+      "recognitionRank": 51,
+      "localClocks": true
     },
     "canaryUrl": "https://www.fancourier.ro/awb-tracking/",
     "trackingUrlTemplate": "https://www.fancourier.ro/awb-tracking/?tracking={trackingNumber}",
@@ -6109,7 +6111,9 @@
     "timezone": "Europe/Budapest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "foxpost",
+      "recognitionRank": 52,
+      "localClocks": true
     },
     "canaryUrl": "https://foxpost.hu/csomagkovetes/",
     "trackingUrlTemplate": "https://foxpost.hu/csomagkovetes/?code={trackingNumber}",
@@ -7648,9 +7652,11 @@
     "timezone": "Europe/Bucharest",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "sameday",
+      "recognitionRank": 53
     },
     "canaryUrl": "https://sameday.ro/",
+    "trackingSearchUrl": "https://sameday.ro/",
     "linkRules": [],
     "detectionRules": [
       {

package/data/coverage-summary.json

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

package/data/detection-golden.json

@@ -8410,6 +8410,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8418,6 +8421,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8426,6 +8432,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8434,6 +8443,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8442,6 +8454,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8450,6 +8465,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8458,6 +8476,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8466,6 +8487,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8474,6 +8498,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {
@@ -8482,6 +8509,9 @@
     "confidence": "low",
     "candidates": [
       "sameday"
+    ],
+    "asked": [
+      "sameday"
     ]
   },
   {

package/dist/browser/scraper.js

@@ -4878,7 +4878,9 @@ var ye = {
 		timezone: "Europe/Bucharest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "fan-courier",
+			recognitionRank: 51,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.fancourier.ro/awb-tracking/",
 		trackingUrlTemplate: "https://www.fancourier.ro/awb-tracking/?tracking={trackingNumber}",
@@ -4906,7 +4908,9 @@ var ye = {
 		timezone: "Europe/Budapest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "foxpost",
+			recognitionRank: 52,
+			localClocks: !0
 		},
 		canaryUrl: "https://foxpost.hu/csomagkovetes/",
 		trackingUrlTemplate: "https://foxpost.hu/csomagkovetes/?code={trackingNumber}",
@@ -6058,9 +6062,11 @@ var ye = {
 		timezone: "Europe/Bucharest",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "sameday",
+			recognitionRank: 53
 		},
 		canaryUrl: "https://sameday.ro/",
+		trackingSearchUrl: "https://sameday.ro/",
 		linkRules: [],
 		detectionRules: [{
 			pattern: "^1[A-Z]{3,5}\\d{9,11}$",
@@ -11683,7 +11689,9 @@ var _c = {
 	"dpd-de": 65,
 	"dpd-pl": 8,
 	emile: 4,
+	"fan-courier": 51,
 	"four-px": 13,
+	foxpost: 52,
 	"gls-ch": 50,
 	"gls-de": 60,
 	"gls-fr": 61,
@@ -11707,6 +11715,7 @@ var _c = {
 	postnord: 7,
 	purolator: 12,
 	"relais-colis": 25,
+	sameday: 53,
 	seur: 43,
 	sto: 10,
 	"swiss-post-cargo": 11,

package/dist/carriers/fan-courier/adapter.d.ts

@@ -0,0 +1,12 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class FanCourierTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

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

@@ -0,0 +1,51 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
+import { normalizeFanCourierNumber, parseFanCourier, PROVIDER } from './parser.js';
+/** The tracking page's own lookup, which it posts as a form. */
+const ENDPOINT = 'https://www.fancourier.ro/limit-tracking.php';
+// Cloudflare's interstitial, served with a 200 or a 403.
+const CHALLENGE = /<title>\s*(?:Just a moment|Attention Required)|\bcf[-_]chl|challenge-platform/i;
+export class FanCourierTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeFanCourierNumber(raw);
+        return runSteps({ carrier: 'fan-courier', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    signal.throwIfAborted();
+                    const { response, bytes } = await fetchBounded(ENDPOINT, { method: 'POST', signal,
+                        headers: { Accept: 'application/json', 'User-Agent': userAgentOf(this.options.userAgent) },
+                        // The English page's locale, which words the events in English.
+                        body: new URLSearchParams({ action: 'get_awb', awb: number, lang: 'en-US' }),
+                    }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
+                        allowHttpStatuses: [404, 422], fetcher: this.options.fetcher });
+                    // The number was checked before the request: a rejection or a missing page says nothing about the parcel.
+                    if (response.status !== 200)
+                        throw new IndeterminateError(PROVIDER, 'FAN Courier tracking is unavailable');
+                    const text = decodeText(bytes.subarray(0, 4_096));
+                    if (CHALLENGE.test(text))
+                        throw new ChallengeError(PROVIDER, 'FAN Courier asked for a browser check');
+                    // The page asks again after an empty reply, as after a rate limit.
+                    if (!text.trim())
+                        throw new IndeterminateError(PROVIDER, 'FAN Courier returned an empty reply');
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, PROVIDER);
+                    }
+                    catch (cause) {
+                        throw new SchemaError(PROVIDER, 'FAN Courier returned invalid tracking JSON', { cause });
+                    }
+                    return parseFanCourier(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new FanCourierTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return { id: 'fan-courier', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeFanCourierNumber(number))) };
+};

package/dist/carriers/fan-courier/carrier.json

@@ -17,18 +17,54 @@
   "timezone": "Europe/Bucharest",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "fan-courier",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 51
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code"
+  ],
   "portal": {
     "url": "https://www.fancourier.ro/awb-tracking/?tracking={trackingNumber}",
     "searchUrl": "https://www.fancourier.ro/awb-tracking/",
     "canaryUrl": "https://www.fancourier.ro/awb-tracking/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "milestones",
+      "awb_date",
+      "related_awb_numbers",
+      "recipient_name"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code"
+    ],
+    "discarded": [
+      "milestones",
+      "awb_date",
+      "related_awb_numbers",
+      "recipient_name",
+      "order_contents",
+      "weight",
+      "dimensions",
+      "payment_details",
+      "service_options"
+    ],
+    "unavailable": [
+      "eta",
+      "pickup_point",
+      "sender_name",
+      "offset_timestamps"
+    ]
   },
   "links": [
     {

package/dist/carriers/fan-courier/numbers.json

@@ -161,7 +161,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -174,7 +174,7 @@
           "korea-post"
         ]
       },
-      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; the capture was not opened."
+      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; FAN Courier's tracking returns its history."
     },
     {
       "number": "7000025622933",
@@ -187,7 +187,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -199,7 +199,7 @@
           "yunda"
         ]
       },
-      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; the capture holds only the page shell."
+      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; FAN Courier's tracking returns its history."
     },
     {
       "number": "7000090535614",
@@ -212,7 +212,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -224,7 +224,7 @@
           "yunda"
         ]
       },
-      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; the capture was not opened."
+      "note": "Looked up on FAN Courier's own tracker, as an archived address shows; FAN Courier's tracking returns its history."
     }
   ]
 }

package/dist/carriers/fan-courier/parser.d.ts

@@ -0,0 +1,11 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "FAN Courier";
+/** A thirteen-digit AWB, the only length FAN Courier's documentation, clients and tracker show. */
+export declare function normalizeFanCourierNumber(raw: string): string;
+/**
+ * The tracker's reply for one AWB: its events, oldest first, each with its
+ * code, wording, town and wall clock. The contents, weight, dimensions, the
+ * payment date, the related AWBs and the masked name of whoever signed are
+ * never read.
+ */
+export declare function parseFanCourier(payload: unknown, raw: string): CarrierResult;

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

@@ -0,0 +1,92 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { clean, cleanScalar } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { fanCourierStage } from './status.js';
+export const PROVIDER = 'FAN Courier';
+const MAX_EVENTS = 500;
+// The tracker's answer for an AWB it does not know, in English and in Romanian.
+const ABSENT = new Set(['the awb was not found', 'awb-ul nu a fost gasit']);
+/** A thirteen-digit AWB, the only length FAN Courier's documentation, clients and tracker show. */
+export function normalizeFanCourierNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^\d{13}$/.test(number))
+        throw new InvalidInputError(PROVIDER, 'FAN Courier requires a thirteen-digit AWB number');
+    return number;
+}
+/** A scan's wall clock. The reply gives no offset, so the clock stays local. */
+function clock(raw) {
+    if (raw != null && typeof raw !== 'string')
+        throw new SchemaError(PROVIDER, 'FAN Courier returned an invalid scan clock');
+    const text = clean(raw, 32);
+    const parsed = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text)
+        ? DateTime.fromFormat(text, 'yyyy-MM-dd HH:mm:ss', { zone: 'UTC' }) : null;
+    return parsed?.isValid ? { local_time: parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) }
+        : text ? { provider_time_text: text } : {};
+}
+/**
+ * The tracker's reply for one AWB: its events, oldest first, each with its
+ * code, wording, town and wall clock. The contents, weight, dimensions, the
+ * payment date, the related AWBs and the masked name of whoever signed are
+ * never read.
+ */
+export function parseFanCourier(payload, raw) {
+    const number = normalizeFanCourierNumber(raw);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER);
+    if (payload.awbNumber == null) {
+        // An unknown AWB comes back without one, the requested number in `content`
+        // and the page's message.
+        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) {
+            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) {
+        throw new SchemaError(PROVIDER, 'FAN Courier answered for a different AWB');
+    }
+    const rows = payload.events;
+    if (!Array.isArray(rows) || rows.length > MAX_EVENTS)
+        throw new SchemaError(PROVIDER, 'FAN Courier returned invalid events');
+    // The tracker shows an error for an AWB without events: it proves neither a parcel on its way nor absence.
+    if (!rows.length)
+        throw new IndeterminateError(PROVIDER, 'FAN Courier returned no events for the AWB');
+    const scans = rows.map(row => {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'FAN Courier returned an invalid event');
+        const code = cleanScalar(row.id, 16);
+        const description = clean(row.name, 300);
+        if (!/^[A-Z]{1,3}\d{1,4}$/.test(code) || !description) {
+            throw new SchemaError(PROVIDER, 'FAN Courier returned an event without its code or wording');
+        }
+        return { code, description, location: clean(row.location, 100), time: clock(row.date) };
+    });
+    // The tracker hides what follows the last delivery, as the page does.
+    const delivered = scans.map(scan => scan.code).lastIndexOf('S2');
+    const kept = delivered === -1 ? scans : scans.slice(0, delivered + 1);
+    const events = [];
+    const seen = new Set();
+    // Newest first; equal clocks keep the reply's order.
+    for (const scan of kept.reverse()) {
+        const stage = fanCourierStage(scan.code);
+        const event = { description: scan.description, provider_code: scan.code, ...scan.time,
+            ...(scan.location ? { location: scan.location } : {}), ...(stage ? { stage } : {}) };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(event);
+        }
+    }
+    const latest = events[0];
+    const stage = fanCourierStage(latest.provider_code);
+    return { status: stage ? languageStageStatus(stage) : 'unknown', ...(stage ? { current_stage: stage } : {}),
+        last_status_text: latest.description ?? null, last_update: null, last_update_local: latest.local_time ?? null,
+        events };
+}

package/dist/carriers/fan-courier/status.d.ts

@@ -0,0 +1,10 @@
+import type { Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage of one event code, if the map gives it one. */
+export declare function fanCourierStage(code: string): Stage | undefined;
+/**
+ * What the map says about one scan. Every scan carries its code, so wording
+ * alone gets nothing. Codes whose meaning no source settles (S8, S38, S46,
+ * S49) stay unknown, open for review.
+ */
+export declare const statusMap: CarrierStatusMap;

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

@@ -0,0 +1,46 @@
+const each = (codes, stage) => codes.map(code => [code, stage]);
+/**
+ * FAN Courier's event codes, the same in every language. The names come from
+ * the event list in FAN's API documentation; S56 and S65 are named only by the
+ * tracker's own code. The shared wording rules misread several of them, such
+ * as a parcel taken over for delivery.
+ */
+const CODES = new Map([
+    // The courier collected the parcel from its sender.
+    ['C0', 'accepted'],
+    // Handed in at a FANbox locker or a collect point, for a courier to collect:
+    // the tracker puts it on the same milestone as C0.
+    ['S56', 'accepted'],
+    // Line hauls, sorting and depot scans, and the depot a parcel waits in
+    // between delivery rounds.
+    ...each(['H0', 'H1', 'H2', 'H3', 'H4', 'H10', 'H11', 'H12', 'H13', 'H15', 'H17'], 'in_transit'),
+    // Held for the next transport abroad, which the tracker counts as in transit.
+    ['S65', 'in_transit'],
+    // Redirected, resent for delivery or handed to an external partner: the
+    // parcel goes on, a redirected one under its redirection AWB.
+    ...each(['S9', 'S35', 'S47'], 'in_transit'),
+    // Taken over for delivery, then on the round.
+    ...each(['C1', 'S1'], 'out_for_delivery'),
+    ['S2', 'delivered'],
+    // A round that ended without a delivery: the recipient was notified or
+    // could not be reached, the address was wrong or incomplete, or a later
+    // delivery was agreed.
+    ...each(['S3', 'S4', 'S5', 'S10', 'S11', 'S12', 'S14', 'S19', 'S20', 'S21', 'S22', 'S24', 'S25', 'S27', 'S28', 'S30', 'S42'], 'failed_attempt'),
+    // Refusals, returns and compensation: this AWB will not be delivered. A
+    // return travels back to the sender under its own AWB, so none of these
+    // says the sender has it.
+    ...each(['S6', 'S7', 'S15', 'S16', 'S33', 'S37', 'S43', 'S50'], 'exception'),
+]);
+/** The stage of one event code, if the map gives it one. */
+export function fanCourierStage(code) {
+    return CODES.get(code);
+}
+/**
+ * What the map says about one scan. Every scan carries its code, so wording
+ * alone gets nothing. Codes whose meaning no source settles (S8, S38, S46,
+ * S49) stay unknown, open for review.
+ */
+export const statusMap = {
+    stage: code => (code ? fanCourierStage(code) : undefined),
+    gaps: [],
+};