universal-parcel-scraper 0.93.0-main.987 → 0.94.0-main.990

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 **151 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **153 dedicated adapters** and **5 universal fallbacks**
 
 <sub>208 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 4,117 such statuses, each filed under one stage.
+The carrier folders record 4,279 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

@@ -7916,7 +7916,9 @@
     "timezone": "Europe/Bratislava",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "slovak-parcel-service",
+      "recognitionRank": 830,
+      "localClocks": true
     },
     "canaryUrl": "https://www.sps-sro.sk/moja-zasielka/",
     "trackingUrlTemplate": "https://www.sps-sro.sk/moja-zasielka/?shipment_id={trackingNumber}",
@@ -7953,7 +7955,9 @@
     "timezone": "Europe/Bratislava",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "slovenska-posta",
+      "recognitionRank": 840,
+      "localClocks": true
     },
     "canaryUrl": "https://www.posta.sk/sledovanie-zasielok",
     "trackingUrlTemplate": "https://www.posta.sk/sledovanie-zasielok#parcel={trackingNumber}",
@@ -7982,7 +7986,14 @@
         ]
       }
     ],
-    "detectionRules": []
+    "detectionRules": [
+      {
+        "pattern": "^[A-Z]{2}\\d{9}SK$",
+        "confidence": "low",
+        "checksum": "s10",
+        "preferred": true
+      }
+    ]
   },
   "speedpak": {
     "displayName": "SpeedPAK",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 208,
-  "activeAdapters": 151,
+  "activeAdapters": 153,
   "countries": 66,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -19948,10 +19948,10 @@
     ],
     "asked": [
       "hermes-de",
+      "slovak-parcel-service",
       "dpd",
       "dpd-de",
-      "seur",
-      "brt"
+      "seur"
     ]
   },
   {
@@ -19989,11 +19989,11 @@
       "slovak-parcel-service"
     ],
     "asked": [
+      "slovak-parcel-service",
       "dpd",
       "dpd-de",
       "seur",
-      "brt",
-      "relais-colis"
+      "brt"
     ]
   },
   {
@@ -20015,10 +20015,10 @@
     ],
     "asked": [
       "hermes-de",
+      "slovak-parcel-service",
       "dpd",
       "dpd-de",
-      "seur",
-      "brt"
+      "seur"
     ]
   },
   {
@@ -20038,11 +20038,11 @@
       "slovak-parcel-service"
     ],
     "asked": [
+      "slovak-parcel-service",
       "dpd",
       "dpd-de",
       "seur",
-      "brt",
-      "relais-colis"
+      "brt"
     ]
   },
   {
@@ -25176,6 +25176,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -25390,6 +25391,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -26769,6 +26771,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -26884,6 +26887,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -26986,6 +26990,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -27521,6 +27526,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -27532,6 +27538,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -27638,6 +27645,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -30811,6 +30819,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -30822,6 +30831,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -33590,6 +33600,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -33645,6 +33656,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },
@@ -33975,6 +33987,7 @@
       "intl-post"
     ],
     "asked": [
+      "slovenska-posta",
       "chronopost"
     ]
   },

package/dist/browser/scraper.js

@@ -6274,7 +6274,9 @@ var be = {
 		timezone: "Europe/Bratislava",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "slovak-parcel-service",
+			recognitionRank: 830,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.sps-sro.sk/moja-zasielka/",
 		trackingUrlTemplate: "https://www.sps-sro.sk/moja-zasielka/?shipment_id={trackingNumber}",
@@ -6298,7 +6300,9 @@ var be = {
 		timezone: "Europe/Bratislava",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "slovenska-posta",
+			recognitionRank: 840,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.posta.sk/sledovanie-zasielok",
 		trackingUrlTemplate: "https://www.posta.sk/sledovanie-zasielok#parcel={trackingNumber}",
@@ -6319,7 +6323,12 @@ var be = {
 				params: ["q"]
 			}
 		],
-		detectionRules: []
+		detectionRules: [{
+			pattern: "^[A-Z]{2}\\d{9}SK$",
+			confidence: "low",
+			checksum: "s10",
+			preferred: !0
+		}]
 	},
 	speedpak: {
 		displayName: "SpeedPAK",
@@ -7184,7 +7193,7 @@ var be = {
 	saia: [],
 	sameday: ["sameday-1"],
 	"slovak-parcel-service": ["slovak-parcel-service-1"],
-	"slovenska-posta": [],
+	"slovenska-posta": ["slovenska-posta-s10"],
 	speedpak: ["speedpak-1"],
 	speedy: [],
 	"spx-ph": [
@@ -11965,6 +11974,8 @@ var bc = {
 	"relais-colis": 250,
 	sameday: 530,
 	seur: 430,
+	"slovak-parcel-service": 830,
+	"slovenska-posta": 840,
 	speedy: 540,
 	sto: 100,
 	"swiss-post-cargo": 110,

package/dist/carriers/slovak-parcel-service/adapter.d.ts

@@ -0,0 +1,14 @@
+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';
+export declare const SPS_API = "https://backend.sps-sro.sk/api/tracking/";
+export declare class SlovakParcelServiceTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/slovak-parcel-service/adapter.js

@@ -0,0 +1,78 @@
+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 { firstAttemptMs, networkRetryStep } from '../../core/runner/networkRetry.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { normalizeSpsNumber, parseSpsParcelStatus, parseSpsSearch, parseSpsShipment, SPS, SPS_MAX_BYTES, spsParcelStatusTarget, } from './parser.js';
+// The service the tracking page (www.sps-sro.sk/moja-zasielka) calls from the visitor's browser.
+export const SPS_API = 'https://backend.sps-sro.sk/api/tracking/';
+export class SlovakParcelServiceTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeSpsNumber(raw);
+        const get = async (path, signal, deadline, allowHttpStatuses) => {
+            // The service words its notices and scans in Slovak, the language its not-found notice is pinned in.
+            const { response, bytes } = await fetchBounded(`${SPS_API}${path}`, { signal, headers: {
+                    Accept: 'application/json', 'Accept-Language': 'sk', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: SPS, timeoutMs: Math.max(1, Math.floor(deadline - Date.now())), maxBytes: SPS_MAX_BYTES,
+                allowHttpStatuses, fetcher: this.options.fetcher });
+            const text = decodeText(bytes);
+            try {
+                return { status: response.status, payload: JSON.parse(text) };
+            }
+            catch (error) {
+                // A gateway's own error page, or a page for a route that moved, says nothing about the parcel.
+                if (response.status !== 200)
+                    throw new IndeterminateError(SPS, `Slovak Parcel Service returned HTTP ${response.status} without its error reply`, { cause: error });
+                if (/<(?:!doctype|html|head|body)\b/i.test(text))
+                    throw new ChallengeError(SPS, 'Slovak Parcel Service answered with a web page instead of its tracking reply', { cause: error });
+                throw new SchemaError(SPS, 'Slovak Parcel Service returned a reply that is not JSON', { cause: error });
+            }
+        };
+        const read = async (signal, timeoutMs) => {
+            // The shipment, the search and the parcel's own scans share the step's time.
+            const deadline = Date.now() + timeoutMs;
+            const id = encodeURIComponent(number);
+            const shipment = await get(`shipment?shipment_id=${id}`, signal, deadline, [404, 502]);
+            if (shipment.status === 404)
+                throw new IndeterminateError(SPS, 'Slovak Parcel Service tracking service moved');
+            if (shipment.status === 502) {
+                // One failure answers both an unknown number and a shipment whose history did
+                // not load: the search the page runs first tells them apart.
+                if (!isRecord(shipment.payload) || shipment.payload.ok !== false)
+                    throw new SchemaError(SPS, 'Slovak Parcel Service returned an unexpected error reply');
+                const search = await get(`find-shipment?shipment_id=${id}&source=tracking`, signal, deadline, [404]);
+                return parseSpsSearch(search.status, search.payload);
+            }
+            // A shipment without scans has them under its dashed parcel number, as the page asks.
+            const parcel = spsParcelStatusTarget(shipment.payload, number);
+            if (!parcel)
+                return parseSpsShipment(shipment.payload, number);
+            const scans = await get(`parcel-status?parcel_id=${encodeURIComponent(parcel)}`, signal, deadline, [404]);
+            // The shipment exists, so a missing route or parcel leaves only its history open.
+            if (scans.status === 404)
+                throw new IndeterminateError(SPS, 'Slovak Parcel Service did not return the parcel’s scans');
+            return parseSpsShipment(shipment.payload, number, parseSpsParcelStatus(scans.payload, parcel));
+        };
+        // A request that fails to reach SPS, or hangs, gets one more try: the first
+        // gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'slovak-parcel-service', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            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 SlovakParcelServiceTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'slovak-parcel-service', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeSpsNumber(number))),
+    };
+};

package/dist/carriers/slovak-parcel-service/carrier.json

@@ -16,18 +16,59 @@
   "timezone": "Europe/Bratislava",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "slovak-parcel-service",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "localClocks": true,
+    "recognition": {
+      "rank": 830
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "weight"
+  ],
   "portal": {
     "url": "https://www.sps-sro.sk/moja-zasielka/?shipment_id={trackingNumber}",
     "searchUrl": "https://www.sps-sro.sk/moja-zasielka/",
     "canaryUrl": "https://www.sps-sro.sk/moja-zasielka/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "weight",
+      "sender_name",
+      "recipient_name",
+      "postcodes",
+      "customer_reference",
+      "tracking_alias",
+      "delivery_partner_reference",
+      "parcel_count"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code",
+      "weight"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "postcodes",
+      "customer_reference",
+      "tracking_alias",
+      "delivery_partner_reference",
+      "parcel_count"
+    ],
+    "unavailable": [
+      "eta",
+      "offset_timestamps"
+    ]
   },
   "links": [
     {

package/dist/carriers/slovak-parcel-service/numbers.json

@@ -26,7 +26,7 @@
           "evri-uk"
         ]
       },
-      "note": "Looked up on SPS's own tracker, as an archived address shows; the capture was not opened. It carries two digits more than SPS's parcel numbers, and the next address shows the tracker answering with the parcel of those first fourteen digits."
+      "note": "Looked up on SPS's own tracker, as an archived address shows; the capture was not opened. It carries two digits more than SPS's parcel numbers, and the next address shows the tracker answering with the parcel of those first fourteen digits. SPS's tracker accepts that longer form, which its tracking service also uses to name parcels, but no longer knows this one, so no reply ties it to SPS."
     },
     {
       "number": "703-010-30781471",
@@ -58,7 +58,7 @@
           "slovak-parcel-service"
         ]
       },
-      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows; the capture was not opened."
+      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows; the capture was not opened. SPS's tracking service no longer knows it, which can mean its records expired."
     },
     {
       "number": "030-43181455",
@@ -71,7 +71,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -87,7 +87,7 @@
           "dhl-ecommerce-pl"
         ]
       },
-      "note": "Looked up on SPS's own tracker without the 703 country prefix, as an archived address shows; the capture was not opened."
+      "note": "Looked up on SPS's own tracker without the 703 country prefix, as an archived address shows. SPS's tracking service returns the parcel's history for this form too."
     },
     {
       "number": "703-030-43181455",
@@ -100,7 +100,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -118,7 +118,7 @@
           "slovak-parcel-service"
         ]
       },
-      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows; the capture was not opened."
+      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows. SPS's tracking service returns its history."
     },
     {
       "number": "030-43181927",
@@ -131,7 +131,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -144,7 +144,7 @@
           "dhl-ecommerce-pl"
         ]
       },
-      "note": "Looked up on SPS's own tracker without the 703 country prefix, as an archived address shows; the capture was not opened."
+      "note": "Looked up on SPS's own tracker without the 703 country prefix, as an archived address shows. SPS's tracking service returns the history of the parcel with that prefix."
     },
     {
       "number": "703-030-43181927",
@@ -157,7 +157,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -176,7 +176,7 @@
           "slovak-parcel-service"
         ]
       },
-      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows; the capture was not opened."
+      "note": "Named as the parcel of a shipment looked up on SPS's own tracker, as an archived result address shows. SPS's tracking service returns its history."
     },
     {
       "number": "703-030-44933746",
@@ -189,7 +189,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -207,7 +207,7 @@
           "slovak-parcel-service"
         ]
       },
-      "note": "Looked up on SPS's own tracker, as an archived address shows; the capture was not opened."
+      "note": "Looked up on SPS's own tracker, as an archived address shows. SPS's tracking service returns its history."
     }
   ]
 }

package/dist/carriers/slovak-parcel-service/parser.d.ts

@@ -0,0 +1,36 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const SPS = "Slovak Parcel Service";
+export declare const SPS_MAX_BYTES: number;
+/** An SPS parcel number in the compact form its tracking service accepts. */
+export declare function normalizeSpsNumber(raw: string): string;
+/**
+ * Whether a number the reply gives names the requested parcel: the same
+ * number, or a shorter form of the same barcode. Two barcodes must agree in full.
+ */
+export declare function samePackage(requested: string, id: string): boolean;
+/**
+ * The parcel whose own scans the website asks for when a shipment comes
+ * without them: one with a dashed parcel number, the requested one first.
+ * Null when the reply has scans or no such parcel.
+ */
+export declare function spsParcelStatusTarget(payload: unknown, raw: string): string | null;
+/** The rows of a `parcel-status` reply for `parcel`, which must all name that parcel. */
+export declare function parseSpsParcelStatus(payload: unknown, parcel: string): unknown[];
+/**
+ * The reply of `GET /api/tracking/shipment`. The shipment, each parcel and
+ * each scan name their numbers; one of them must be the requested parcel or
+ * the barcode it is short for. The shipper, receiver, receiver's name,
+ * destination postcode, references, remarks and the handheld's coordinates in
+ * the same reply are never read. `rows` replaces the reply's scans with those
+ * a `parcel-status` request returned.
+ */
+export declare function parseSpsShipment(payload: unknown, raw: string, rows?: readonly unknown[]): CarrierResult;
+/** The search's notice for a number SPS does not know. */
+export declare const SPS_NOT_FOUND_TITLE = "Z\u00E1sielku sa n\u00E1m nepodarilo n\u00E1js\u0165";
+/**
+ * The website search's answer (`GET /api/tracking/find-shipment`) after the
+ * shipment request failed upstream. A 404 with the not-found notice is an
+ * unknown number; the address of the shipment's page means SPS knows it and
+ * only its history failed. Anything else proves nothing.
+ */
+export declare function parseSpsSearch(status: number, payload: unknown): never;