universal-parcel-scraper 0.372.0-main.2012 → 0.373.0-main.2014

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 **402 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **403 dedicated adapters** and **5 universal fallbacks**
 
 <sub>727 catalog entries · 133 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 13,584 such statuses, each filed under one stage.
+The carrier folders record 13,597 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

@@ -22117,9 +22117,11 @@
     "timezone": "Europe/Tirane",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "posta-shqiptare",
+      "recognitionRank": 829,
+      "localClocks": true
     },
-    "canaryUrl": "https://www.postashqiptare.al/c/207/tracked",
+    "canaryUrl": "https://eposta.postashqiptare.al/tracking",
     "trackingUrlTemplate": "https://eposta.postashqiptare.al/tracking/{trackingNumber}",
     "trackingSearchUrl": "https://www.postashqiptare.al/c/207/tracked",
     "linkRules": [
@@ -22130,7 +22132,14 @@
         "path": "^/tracking/([^/?#]+)/?$"
       }
     ],
-    "detectionRules": []
+    "detectionRules": [
+      {
+        "pattern": "^[A-Z]{2}\\d{9}AL$",
+        "confidence": "low",
+        "checksum": "s10",
+        "preferred": true
+      }
+    ]
   },
   "posta-slovenije": {
     "displayName": "Pošta Slovenije",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 727,
-  "activeAdapters": 402,
+  "activeAdapters": 403,
   "countries": 133,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -64492,6 +64492,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },
@@ -64562,6 +64563,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },
@@ -67006,6 +67008,19 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
+      "chronopost"
+    ]
+  },
+  {
+    "input": "EE200190512AL",
+    "carrier": "intl-post",
+    "confidence": "high",
+    "candidates": [
+      "intl-post"
+    ],
+    "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },
@@ -73651,6 +73666,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },
@@ -73662,6 +73678,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },
@@ -73673,6 +73690,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-shqiptare",
       "chronopost"
     ]
   },

package/dist/browser/scraper.js

@@ -16778,16 +16778,23 @@ var Pe = {
 		timezone: "Europe/Tirane",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "posta-shqiptare",
+			recognitionRank: 829,
+			localClocks: !0
 		},
-		canaryUrl: "https://www.postashqiptare.al/c/207/tracked",
+		canaryUrl: "https://eposta.postashqiptare.al/tracking",
 		trackingUrlTemplate: "https://eposta.postashqiptare.al/tracking/{trackingNumber}",
 		trackingSearchUrl: "https://www.postashqiptare.al/c/207/tracked",
 		linkRules: [{
 			domains: ["eposta.postashqiptare.al"],
 			path: "^/tracking/([^/?#]+)/?$"
 		}],
-		detectionRules: []
+		detectionRules: [{
+			pattern: "^[A-Z]{2}\\d{9}AL$",
+			confidence: "low",
+			checksum: "s10",
+			preferred: !0
+		}]
 	},
 	"posta-slovenije": {
 		displayName: "Pošta Slovenije",
@@ -22638,7 +22645,7 @@ var Pe = {
 	"posta-moldovei": ["posta-moldovei-1"],
 	"posta-north-macedonia": ["posta-north-macedonia-s10"],
 	"posta-romana": ["posta-romana-s10"],
-	"posta-shqiptare": [],
+	"posta-shqiptare": ["posta-shqiptare-s10"],
 	"posta-slovenije": ["posta-slovenije-s10"],
 	"posta-srbije": ["posta-srbije-s10"],
 	postaplus: [],
@@ -28158,6 +28165,7 @@ var pl = {
 	"post-luxembourg": 80,
 	"posta-north-macedonia": 899,
 	"posta-romana": 948,
+	"posta-shqiptare": 829,
 	"posta-slovenije": 130,
 	"posta-srbije": 110,
 	"poste-italiane": 900,

package/dist/carriers/posta-shqiptare/adapter.d.ts

@@ -0,0 +1,15 @@
+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';
+/** The lookup the e-Posta tracking page makes, with the item's code as the last part of the address. */
+export declare const POSTA_SHQIPTARE_API = "https://eposta.postashqiptare.al:8443/api/mailItemEvents/getTrackApi";
+export declare class PostaShqiptareTracker {
+    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/posta-shqiptare/adapter.js

@@ -0,0 +1,73 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, NotFoundError, SchemaError, TransportError } 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 { normalizePostaShqiptareNumber, parsePostaShqiptare, POSTA_SHQIPTARE_MAX_BYTES, PROVIDER } from './parser.js';
+/** The lookup the e-Posta tracking page makes, with the item's code as the last part of the address. */
+export const POSTA_SHQIPTARE_API = 'https://eposta.postashqiptare.al:8443/api/mailItemEvents/getTrackApi';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// Bot checks a CDN or firewall could put in place of the reply.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|challenge-platform|<title>\s*(?:Just a moment|Attention Required|Request Rejected|Access Denied)|requested URL was rejected/i;
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'Posta Shqiptare answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned a reply that is not JSON', { cause });
+    }
+}
+/** Whether an error reply is the page's own notice for a missing item. */
+function missing(body) {
+    try {
+        return JSON.parse(body) === 'package_not_found';
+    }
+    catch {
+        return false;
+    }
+}
+export class PostaShqiptareTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizePostaShqiptareNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(`${POSTA_SHQIPTARE_API}/${number}`, { method: 'GET', signal, headers: {
+                    Accept: 'application/json', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: POSTA_SHQIPTARE_MAX_BYTES,
+                redirect: 'manual', fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 400, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'Posta Shqiptare redirected its tracking lookup');
+            const body = decodeText(bytes);
+            if (response.status !== 200) {
+                if (response.status !== 410 && missing(body))
+                    throw new NotFoundError(PROVIDER);
+                // The tracker answers an unknown code with HTTP 200; a 404 is a moved route.
+                if (response.status === 400)
+                    throw new IndeterminateError(PROVIDER, 'Posta Shqiptare refused the lookup');
+                throw new TransportError(PROVIDER, 'Posta Shqiptare tracking lookup is unavailable');
+            }
+            return parsePostaShqiptare(json(body), number);
+        };
+        // A request that fails to reach the tracker, or hangs, gets one more try: the
+        // first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'posta-shqiptare', 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 PostaShqiptareTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'posta-shqiptare', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizePostaShqiptareNumber(number))),
+    };
+};

package/dist/carriers/posta-shqiptare/carrier.json

@@ -19,18 +19,44 @@
   "timezone": "Europe/Tirane",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "posta-shqiptare",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 829
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location"
+  ],
   "portal": {
     "url": "https://eposta.postashqiptare.al/tracking/{trackingNumber}",
     "searchUrl": "https://www.postashqiptare.al/c/207/tracked",
-    "canaryUrl": "https://www.postashqiptare.al/c/207/tracked",
-    "shows": [],
-    "scraped": [],
+    "canaryUrl": "https://eposta.postashqiptare.al/tracking",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
     "discarded": [],
-    "unavailable": []
+    "unavailable": [
+      "eta",
+      "weight",
+      "service_name",
+      "pickup_point",
+      "offset_timestamps",
+      "proof_of_delivery",
+      "delivery_tracking_number"
+    ]
   },
   "links": [
     {
@@ -40,5 +66,13 @@
       "path": "^/tracking/([^/?#]+)/?$"
     }
   ],
-  "detection": []
+  "detection": [
+    {
+      "id": "posta-shqiptare-s10",
+      "pattern": "^[A-Z]{2}\\d{9}AL$",
+      "confidence": "low",
+      "preferred": true,
+      "checksum": "s10"
+    }
+  ]
 }

package/dist/carriers/posta-shqiptare/numbers.json

@@ -12,13 +12,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "Looked up on Posta Shqiptare's e-Posta tracker; the opened capture holds only the app shell, which loads the history by script."
+      "note": "Looked up on Posta Shqiptare's e-Posta tracker; the opened capture holds only the app shell, which loads the history by script. Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
     },
     {
       "number": "EE200190509AL",
@@ -30,13 +30,13 @@
       },
       "context": {
         "service": "EMS",
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Albania Post page offered it as a sample to try; it is not described as a live shipment."
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
     },
     {
       "number": "CP339538880AL",
@@ -48,13 +48,13 @@
       },
       "context": {
         "service": "Parcel",
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Albania Post page offered it as a sample to try; it is not described as a live shipment."
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
     },
     {
       "number": "LG014636582AL",
@@ -65,13 +65,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Albania Post page offered it as a sample to try; it is not described as a live shipment."
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
     },
     {
       "number": "LG014771021AL",
@@ -82,13 +82,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Albania Post page offered it as a sample to try; it is not described as a live shipment."
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
     },
     {
       "number": "LG010568652AL",
@@ -99,13 +99,33 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Albania Post page offered it as a sample to try; it is not described as a live shipment."
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history. Detection selects the generic postal carrier."
+    },
+    {
+      "number": "EE200190512AL",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.parcelpanel.com/couriers/posta-shqiptare/",
+        "date": "2026-10-18",
+        "dateKind": "capture",
+        "access": "full_page"
+      },
+      "context": {
+        "service": "EMS",
+        "assessment": "confirmed"
+      },
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "ParcelPanel's Albania Post page offered it as a sample to try; Posta Shqiptare's own tracker returns its history, with the scans of the courier that carried it abroad. Detection selects the generic postal carrier."
     }
   ]
 }

package/dist/carriers/posta-shqiptare/parser.d.ts

@@ -0,0 +1,14 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Posta Shqiptare";
+export declare const POSTA_SHQIPTARE_MAX_BYTES: number;
+/** Posta Shqiptare's tracker follows S10 item codes: its own, ending AL, and those other posts send to Albania. */
+export declare function normalizePostaShqiptareNumber(raw: string): string;
+/**
+ * The reply of the e-Posta tracker's `getTrackApi` for one item: its scans,
+ * newest first, each with a wall clock, the wording and the office or the
+ * foreign post's country. The reply does not repeat the number; the request's
+ * address holds the whole of it. A code without scans gets an empty list,
+ * which the page reports as having no events, and the page's own notices for
+ * a missing item are read the same way.
+ */
+export declare function parsePostaShqiptare(payload: unknown, raw: string): CarrierResult;

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

@@ -0,0 +1,150 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { countryCode, isoTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { postaShqiptareStage } from './status.js';
+export const PROVIDER = 'Posta Shqiptare';
+// A long history is a few kilobytes.
+export const POSTA_SHQIPTARE_MAX_BYTES = 256 * 1024;
+const ZONE = 'Europe/Tirane';
+const MAX_ROWS = 500;
+// The tracker's wall clock, with no offset.
+const WALL_CLOCK = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.\d{1,7})?$/;
+// The notices the tracker's page shows for a code it does not have.
+const MISSING = new Set(['Pakoja nuk ekziston', 'package_not_found']);
+// Between a scan's Albanian wording and the IPS event name in English that
+// Posta Shqiptare's own scans add: "Pranim objekti nga klienti / Receive item from customer".
+const HALVES = /^(.*?)\s*\/(?:\s+(.*))?$/;
+// A delivery's wording, which could go on to name who took the item.
+const DELIVERY = /^(?:dorëzuar|dorezuar|objekti u dorëzua|objekti u dorezua)(?=$|[\s,;:.\-–])/i;
+// A run of four digits or more, as a postcode is written, names the delivery area.
+const POSTCODE = /\d{4,}/;
+const ENGLISH_REGIONS = new Intl.DisplayNames(['en'], { type: 'region' });
+const ALBANIAN_REGIONS = new Intl.DisplayNames(['sq'], { type: 'region' });
+/** A name compared without case, accents or spacing differences. */
+const nameKey = (name) => name.normalize('NFD').replace(/\p{Mn}/gu, '').toUpperCase().replace(/\s+/g, ' ').trim();
+// The country names the tracker writes for a foreign post's scans, in Albanian ("Gjermani").
+const ALBANIAN_COUNTRIES = new Map(Array.from({ length: 26 * 26 }, (_, index) => String.fromCharCode(65 + Math.floor(index / 26), 65 + (index % 26)))
+    .filter(code => countryCode(code) === code)
+    .map(code => [nameKey(ALBANIAN_REGIONS.of(code) ?? code), code]));
+/** Posta Shqiptare's tracker follows S10 item codes: its own, ending AL, and those other posts send to Albania. */
+export function normalizePostaShqiptareNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    if (isValidS10TrackingNumber(number))
+        return number;
+    throw new InvalidInputError(PROVIDER, 'Posta Shqiptare tracks S10 item codes');
+}
+/** A text field the reply may leave out or null; anything but a string is a changed reply. */
+function text(row, key, maxLength) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `Posta Shqiptare returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+/**
+ * The scan's wording as the page shows it, without an empty English half. A
+ * delivery keeps only its own words, as anything after them could name who
+ * took the item. `own` is true for Posta Shqiptare's own scans, the ones that
+ * add the IPS event name in English.
+ */
+function wordingOf(raw) {
+    const halves = HALVES.exec(raw);
+    const albanian = halves ? halves[1] : raw;
+    const english = halves?.[2] ?? '';
+    const delivery = DELIVERY.exec(albanian);
+    const own = delivery ? delivery[0] : albanian;
+    return { description: english ? `${own} / ${english}` : own, own: Boolean(english) };
+}
+/** The scan's place: a foreign post's country by its English name, else the office as the tracker names it. */
+function placeOf(office) {
+    const code = ALBANIAN_COUNTRIES.get(nameKey(office)) ?? countryCode(office);
+    if (code)
+        return ENGLISH_REGIONS.of(code) ?? office;
+    return POSTCODE.test(office) ? '' : office;
+}
+/**
+ * When the scan happened. Posta Shqiptare's own scans are on Tirana's clock.
+ * The scans it relays from a foreign post or a courier carry a clock hours
+ * off that partner's own, so they keep their wall clock without an offset, as
+ * does a wall clock the clocks skip or repeat in Albania.
+ */
+function clockOf(raw, own) {
+    const wall = WALL_CLOCK.exec(raw)?.[1] ?? '';
+    // Parsing in UTC checks the calendar digits only; Luxon rolls 24:00 over, so the clock must read back unchanged.
+    const parsed = DateTime.fromISO(wall, { zone: 'UTC' });
+    if (!wall || !parsed.isValid || parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== wall) {
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned an invalid scan time');
+    }
+    if (own && DateTime.fromISO(wall, { zone: ZONE }).getPossibleOffsets().length === 1) {
+        const placed = isoTime(wall, ZONE);
+        if (placed?.iso.startsWith(wall))
+            return { time: placed.iso };
+    }
+    return { local_time: wall };
+}
+function scanOf(row) {
+    if (!isRecord(row))
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned an invalid scan');
+    const { description, own } = wordingOf(text(row, 'description', 300));
+    if (!description)
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned a scan without wording');
+    const clock = clockOf(text(row, 'date', 40), own);
+    const location = placeOf(text(row, 'office', 120));
+    const staged = postaShqiptareStage(description);
+    return {
+        ...clock,
+        description,
+        ...(location ? { location } : {}),
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+}
+/**
+ * The reply of the e-Posta tracker's `getTrackApi` for one item: its scans,
+ * newest first, each with a wall clock, the wording and the office or the
+ * foreign post's country. The reply does not repeat the number; the request's
+ * address holds the whole of it. A code without scans gets an empty list,
+ * which the page reports as having no events, and the page's own notices for
+ * a missing item are read the same way.
+ */
+export function parsePostaShqiptare(payload, raw) {
+    normalizePostaShqiptareNumber(raw);
+    if (typeof payload === 'string' && MISSING.has(payload.trim()))
+        throw new NotFoundError(PROVIDER);
+    if (!Array.isArray(payload))
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned an invalid reply');
+    if (!payload.length)
+        throw new NotFoundError(PROVIDER);
+    if (payload.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'Posta Shqiptare returned an oversized history');
+    const seen = new Set();
+    const events = [];
+    for (const row of payload) {
+        const event = scanOf(row);
+        const identity = JSON.stringify(event);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        events.push(event);
+    }
+    // Newest first, as the page lists them; an oldest-first reply is turned round.
+    const wall = (event) => (event.time ?? event.local_time);
+    if (wall(events[0]).slice(0, 19) < wall(events.at(-1)).slice(0, 19))
+        events.reverse();
+    const latest = events[0];
+    const scanned = events.find(event => event.stage);
+    const stage = scanned?.stage;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: scanned.stage_source } : {}),
+        last_status_text: latest.description,
+        last_update: latest.time ?? null,
+        ...(latest.time ? {} : { last_update_local: latest.local_time }),
+        expected_delivery: null,
+        events,
+    };
+}

package/dist/carriers/posta-shqiptare/status.d.ts

@@ -0,0 +1,11 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage the map gives Posta Shqiptare's wording, if it knows it. */
+export declare function postaShqiptareScanStage(wording: string): Stage | undefined;
+/**
+ * A scan's stage from the map, else from the shared wording rules. Wording
+ * neither knows stays without a stage, so it remains visible for review.
+ */
+export declare function postaShqiptareStage(wording: string): ClassifiedWording | null;
+/** The scans carry wording only. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/posta-shqiptare/status.js

@@ -0,0 +1,53 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * Posta Shqiptare's tracker words each scan in Albanian. Its own scans add the
+ * IPS event name in English after a slash; the scans it relays from a foreign
+ * post, and from the courier that carries some EMS items abroad, have the
+ * Albanian wording alone. The scans carry no code. The map reads the Albanian
+ * wording, without accents, since the relayed scans are written without them
+ * and the courier's with them.
+ */
+const STAGES = new Map([
+    ['pranim objekti nga klienti', 'accepted'],
+    // Taken out of its bag at the office of exchange or a sorting centre.
+    ['objekti u nxor nga thesi per perpunim', 'in_transit'],
+    // The foreign post's office of exchange received it.
+    ['objekti u pranua ne zyren e shkembimit', 'in_transit'],
+    // Presented to customs, or held there, in the destination country.
+    ['regjistrimi i informacionit doganor te objektit', 'customs'],
+    // Sent on from the office of exchange.
+    ['objekti u dergua ne zyren destinacion', 'in_transit'],
+    ['objekti u pranua ne zyren e shperndarjes', 'in_transit'],
+    ['tentative e pasuksesshme ne shperndarjen e objektit', 'failed_attempt'],
+    ['objekti u dorezua', 'delivered'],
+    // The courier's scans.
+    ['nisur nga origjina', 'in_transit'],
+    ['mbajtur ne dogane', 'customs'],
+    ['mberritur ne qendren e shperndarjes', 'in_transit'],
+    // Seen between the arrival at the delivery centre and the delivery; it does not say the item went out.
+    ['marre nga korrieri', 'in_transit'],
+    ['dorezuar', 'delivered'],
+]);
+/** The Albanian wording, before the English half, without accents. */
+const albanianOf = (wording) => normalizeStatusWording(wording).split(/\s+\/(?:\s|$)/, 1)[0].normalize('NFD').replace(/\p{Mn}/gu, '');
+/** The stage the map gives Posta Shqiptare's wording, if it knows it. */
+export function postaShqiptareScanStage(wording) {
+    return STAGES.get(albanianOf(wording));
+}
+/**
+ * A scan's stage from the map, else from the shared wording rules. Wording
+ * neither knows stays without a stage, so it remains visible for review.
+ */
+export function postaShqiptareStage(wording) {
+    const mapped = postaShqiptareScanStage(wording);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+/** The scans carry wording only. */
+export const statusMap = {
+    stage: (code, wording) => (code ? undefined : postaShqiptareScanStage(wording)),
+    gaps: [],
+};

package/dist/carriers/posta-shqiptare/statuses.json

@@ -1,4 +1,18 @@
 {
   "carrier": "posta-shqiptare",
-  "entries": []
+  "entries": [
+    {"wording": "Pranim objekti nga klienti / Receive item from customer", "stage": "accepted", "language": "sq", "confirmedBy": "live", "note": "Posted at a Posta Shqiptare office; UPU's tracker has the posting at the same minute."},
+    {"wording": "Objekti u nxor nga thesi per perpunim / Receive item at location (Inb)", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "Taken out of its bag for processing, seen at the office of exchange before the item leaves Albania."},
+    {"wording": "Objekti u pranua ne zyren e shkembimit", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: its office of exchange received the item (UPU EMD)."},
+    {"wording": "Regjistrimi i informacionit doganor te objektit", "stage": "customs", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: presented to customs or held there (UPU EDB and EME)."},
+    {"wording": "Objekti u dergua ne zyren destinacion", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: sent on from its office of exchange (UPU EMF)."},
+    {"wording": "Objekti u pranua ne zyren e shperndarjes", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: the delivery office received the item (UPU EMG)."},
+    {"wording": "Tentative e pasuksesshme ne shperndarjen e objektit", "stage": "failed_attempt", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: an unsuccessful delivery (UPU EMH); a delivery can follow."},
+    {"wording": "Objekti u dorezua", "stage": "delivered", "language": "sq", "confirmedBy": "live", "note": "Relayed from the foreign post: the final delivery (UPU EMI)."},
+    {"wording": "Nisur nga origjina", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "A courier's scan on an EMS item it carried abroad: it left Albania."},
+    {"wording": "Mbajtur ne dogane", "stage": "customs", "language": "sq", "confirmedBy": "live", "note": "A courier's scan: held at customs in the destination country."},
+    {"wording": "Mbërritur në qendrën e shpërndarjes", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "A courier's scan: arrived at its delivery centre."},
+    {"wording": "Marrë nga korrieri", "stage": "in_transit", "language": "sq", "confirmedBy": "live", "note": "A courier's scan, seen between the arrival at the delivery centre and the delivery; it does not say the item went out for delivery."},
+    {"wording": "Dorëzuar", "stage": "delivered", "language": "sq", "confirmedBy": "live", "note": "A courier's delivery."}
+  ]
 }

package/dist/core/catalog/statusMaps.js

@@ -230,6 +230,7 @@ import { statusMap as posIndonesia } from '../../carriers/pos-indonesia/status.j
 import { statusMap as postLuxembourg } from '../../carriers/post-luxembourg/status.js';
 import { statusMap as postaNorthMacedonia } from '../../carriers/posta-north-macedonia/status.js';
 import { statusMap as postaRomana } from '../../carriers/posta-romana/status.js';
+import { statusMap as postaShqiptare } from '../../carriers/posta-shqiptare/status.js';
 import { statusMap as postaSlovenije } from '../../carriers/posta-slovenije/status.js';
 import { statusMap as postaSrbije } from '../../carriers/posta-srbije/status.js';
 import { statusMap as postlogistics } from '../../carriers/postlogistics/status.js';
@@ -360,6 +361,7 @@ export const STATUS_MAPS = {
     'pfc-express': pfcExpress, phlpost,
     'pitney-bowes': pitneyBowes, 'pos-indonesia': posIndonesia,
     'post-luxembourg': postLuxembourg, 'posta-north-macedonia': postaNorthMacedonia, 'posta-romana': postaRomana,
+    'posta-shqiptare': postaShqiptare,
     'posta-slovenije': postaSlovenije, 'posta-srbije': postaSrbije, postlogistics, posturinn, ppl, 'pro-carrier': proCarrier,
     ptt, raben, redpack, redur, redx, relaytech, 'rl-carriers': rlCarriers, 'rpx-indonesia': rpxIndonesia, sagawa, saia, sailpost, sameday, 'saudi-post': saudiPost, seino, seko,
     sending, serpost, servientrega, sfc, shadowfax, shipentegra, 'skroutz-last-mile': skroutzLastMile, 'skynet-worldwide': skynetWorldwide, 'slovak-parcel-service': slovakParcelService,

package/dist/data/catalog.json

@@ -22117,9 +22117,11 @@
         "timezone": "Europe/Tirane",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "posta-shqiptare",
+            "recognitionRank": 829,
+            "localClocks": true
         },
-        "canaryUrl": "https://www.postashqiptare.al/c/207/tracked",
+        "canaryUrl": "https://eposta.postashqiptare.al/tracking",
         "trackingUrlTemplate": "https://eposta.postashqiptare.al/tracking/{trackingNumber}",
         "trackingSearchUrl": "https://www.postashqiptare.al/c/207/tracked",
         "linkRules": [
@@ -22130,7 +22132,14 @@
                 "path": "^/tracking/([^/?#]+)/?$"
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}AL$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "posta-slovenije": {
         "displayName": "Pošta Slovenije",

package/dist/generated/catalog.d.ts

@@ -14145,16 +14145,23 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Europe/Tirane";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "posta-shqiptare";
+            readonly recognitionRank: 829;
+            readonly localClocks: true;
         };
-        readonly canaryUrl: "https://www.postashqiptare.al/c/207/tracked";
+        readonly canaryUrl: "https://eposta.postashqiptare.al/tracking";
         readonly trackingUrlTemplate: "https://eposta.postashqiptare.al/tracking/{trackingNumber}";
         readonly trackingSearchUrl: "https://www.postashqiptare.al/c/207/tracked";
         readonly linkRules: readonly [{
             readonly domains: readonly ["eposta.postashqiptare.al"];
             readonly path: "^/tracking/([^/?#]+)/?$";
         }];
-        readonly detectionRules: readonly [];
+        readonly detectionRules: readonly [{
+            readonly pattern: "^[A-Z]{2}\\d{9}AL$";
+            readonly confidence: "low";
+            readonly checksum: "s10";
+            readonly preferred: true;
+        }];
     };
     readonly "posta-slovenije": {
         readonly displayName: "Pošta Slovenije";

package/dist/generated/catalog.js

@@ -22118,9 +22118,11 @@ export const CARRIER_CATALOG = {
         "timezone": "Europe/Tirane",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "posta-shqiptare",
+            "recognitionRank": 829,
+            "localClocks": true
         },
-        "canaryUrl": "https://www.postashqiptare.al/c/207/tracked",
+        "canaryUrl": "https://eposta.postashqiptare.al/tracking",
         "trackingUrlTemplate": "https://eposta.postashqiptare.al/tracking/{trackingNumber}",
         "trackingSearchUrl": "https://www.postashqiptare.al/c/207/tracked",
         "linkRules": [
@@ -22131,7 +22133,14 @@ export const CARRIER_CATALOG = {
                 "path": "^/tracking/([^/?#]+)/?$"
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}AL$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "posta-slovenije": {
         "displayName": "Pošta Slovenije",
@@ -30214,7 +30223,7 @@ export const DETECTION_RULE_IDS = {
     "posta-moldovei": ["posta-moldovei-1"],
     "posta-north-macedonia": ["posta-north-macedonia-s10"],
     "posta-romana": ["posta-romana-s10"],
-    "posta-shqiptare": [],
+    "posta-shqiptare": ["posta-shqiptare-s10"],
     "posta-slovenije": ["posta-slovenije-s10"],
     "posta-srbije": ["posta-srbije-s10"],
     "postaplus": [],

package/dist/generated/recognition.js

@@ -211,6 +211,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "post-luxembourg": 80,
     "posta-north-macedonia": 899,
     "posta-romana": 948,
+    "posta-shqiptare": 829,
     "posta-slovenije": 130,
     "posta-srbije": 110,
     "poste-italiane": 900,

package/dist/generated/registry.js

@@ -283,6 +283,7 @@ import { adapter as posMalaysia } from '../carriers/pos-malaysia/adapter.js';
 import { adapter as postLuxembourg } from '../carriers/post-luxembourg/adapter.js';
 import { adapter as postaNorthMacedonia } from '../carriers/posta-north-macedonia/adapter.js';
 import { adapter as postaRomana } from '../carriers/posta-romana/adapter.js';
+import { adapter as postaShqiptare } from '../carriers/posta-shqiptare/adapter.js';
 import { adapter as postaSlovenije } from '../carriers/posta-slovenije/adapter.js';
 import { adapter as postaSrbije } from '../carriers/posta-srbije/adapter.js';
 import { adapter as posteItaliane } from '../carriers/poste-italiane/adapter.js';
@@ -687,6 +688,7 @@ export const REGISTRY = {
         "post-luxembourg": postLuxembourg,
         "posta-north-macedonia": postaNorthMacedonia,
         "posta-romana": postaRomana,
+        "posta-shqiptare": postaShqiptare,
         "posta-slovenije": postaSlovenije,
         "posta-srbije": postaSrbije,
         "poste-italiane": posteItaliane,
@@ -1320,7 +1322,7 @@ export const REGISTRY = {
         "posta-moldovei": "universal",
         "posta-north-macedonia": "posta-north-macedonia",
         "posta-romana": "posta-romana",
-        "posta-shqiptare": "universal",
+        "posta-shqiptare": "posta-shqiptare",
         "posta-slovenije": "posta-slovenije",
         "posta-srbije": "posta-srbije",
         "postaplus": "universal",

package/dist/server/openapi.json

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

package/package.json

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