universal-parcel-scraper 0.90.0-main.979 → 0.91.0-main.981

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 **148 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **149 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,072 such statuses, each filed under one stage.
+The carrier folders record 4,083 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

@@ -7590,7 +7590,8 @@
     "timezone": "Europe/Ljubljana",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "posta-slovenije",
+      "recognitionRank": 790
     },
     "canaryUrl": "https://moja.posta.si/tracking",
     "trackingUrlTemplate": "https://moja.posta.si/tracking?trackingNumber={trackingNumber}",
@@ -7606,7 +7607,14 @@
         ]
       }
     ],
-    "detectionRules": []
+    "detectionRules": [
+      {
+        "pattern": "^[A-Z]{2}\\d{9}SI$",
+        "confidence": "low",
+        "checksum": "s10",
+        "preferred": true
+      }
+    ]
   },
   "posta-srbije": {
     "displayName": "Pošta Srbije",

package/data/coverage-summary.json

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

package/data/detection-golden.json

@@ -25888,6 +25888,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -25899,6 +25900,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -25910,6 +25912,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -26031,6 +26034,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -27080,6 +27084,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -30489,6 +30494,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -30680,6 +30686,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },
@@ -34145,6 +34152,7 @@
       "intl-post"
     ],
     "asked": [
+      "posta-slovenije",
       "chronopost"
     ]
   },

package/dist/browser/scraper.js

@@ -6025,7 +6025,8 @@ var be = {
 		timezone: "Europe/Ljubljana",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "posta-slovenije",
+			recognitionRank: 790
 		},
 		canaryUrl: "https://moja.posta.si/tracking",
 		trackingUrlTemplate: "https://moja.posta.si/tracking?trackingNumber={trackingNumber}",
@@ -6035,7 +6036,12 @@ var be = {
 			pathPattern: "^/tracking/?$",
 			params: ["trackingNumber"]
 		}],
-		detectionRules: []
+		detectionRules: [{
+			pattern: "^[A-Z]{2}\\d{9}SI$",
+			confidence: "low",
+			checksum: "s10",
+			preferred: !0
+		}]
 	},
 	"posta-srbije": {
 		displayName: "Pošta Srbije",
@@ -7153,7 +7159,7 @@ var be = {
 	paquetexpress: [],
 	passport: ["passport-1"],
 	"post-luxembourg": [],
-	"posta-slovenije": [],
+	"posta-slovenije": ["posta-slovenije-s10"],
 	"posta-srbije": [],
 	ppl: [],
 	ptt: ["ptt-1", "ptt-s10"],
@@ -11933,6 +11939,7 @@ var bc = {
 	ontrac: 210,
 	"orlen-paczka": 490,
 	"poczta-polska": 310,
+	"posta-slovenije": 790,
 	"poste-italiane": 460,
 	posti: 270,
 	postlogistics: 260,

package/dist/carriers/posta-slovenije/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 POSTA_SLOVENIJE_ENDPOINT = "https://moja.posta.si/api/v1/parcels/track/";
+export declare const POSTA_SLOVENIJE_USER_AGENT = "MojaPosta/2.5.0 (android)";
+export declare class PostaSlovenijeTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/posta-slovenije/adapter.js

@@ -0,0 +1,70 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, 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, parseJsonBytes } from '../../core/transport/index.js';
+import { isNotFoundReply, normalizePostaSlovenijeNumber, parsePostaSlovenije, POSTA_SLOVENIJE_MAX_BYTES, PROVIDER } from './parser.js';
+// The guest lookup of Pošta Slovenije's MojaPošta app and web tracker. The
+// web tracker sends an invisible reCAPTCHA token with it; the app sends none,
+// and the service answers a client that names itself as the app.
+export const POSTA_SLOVENIJE_ENDPOINT = 'https://moja.posta.si/api/v1/parcels/track/';
+// The app's own User-Agent, "MojaPosta/<version> (<platform>)". The service
+// refuses other clients without a reCAPTCHA token.
+export const POSTA_SLOVENIJE_USER_AGENT = 'MojaPosta/2.5.0 (android)';
+// The service's own JSON refusals: an unknown number, and a client it does not let in.
+const ANSWERS = [403, 404];
+// An edge or firewall page, which can come back with HTTP 200.
+const BLOCKED = /<title>\s*(?:Just a moment|Access Denied|Attention Required|403 Forbidden)|_cf_chl_opt|cf-turnstile|Azure Front Door|Request blocked/i;
+export class PostaSlovenijeTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizePostaSlovenijeNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            // No Content-Type: on a GET the service reads it as an empty JSON body and answers 400.
+            const { response, bytes } = await fetchBounded(`${POSTA_SLOVENIJE_ENDPOINT}?TrackingNumber=${encodeURIComponent(number)}`, {
+                signal, headers: { Accept: 'application/json', 'User-Agent': POSTA_SLOVENIJE_USER_AGENT },
+            }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: POSTA_SLOVENIJE_MAX_BYTES,
+                allowHttpStatuses: ANSWERS, fetcher: this.options.fetcher });
+            let payload;
+            try {
+                payload = parseJsonBytes(bytes, PROVIDER);
+            }
+            catch (cause) {
+                if (response.status === 403 || BLOCKED.test(decodeText(bytes.subarray(0, 64_000)))) {
+                    throw new ChallengeError(PROVIDER, 'Pošta Slovenije answered with a block page', { cause });
+                }
+                if (response.status === 404)
+                    throw new TransportError(PROVIDER, 'Pošta Slovenije tracking service is unavailable', { cause });
+                throw new SchemaError(PROVIDER, 'Pošta Slovenije returned invalid tracking JSON', { cause });
+            }
+            if (response.status === 404) {
+                // Only the service's own notice for this number is a missing parcel; a missing route is not.
+                if (isNotFoundReply(payload, number))
+                    throw new NotFoundError(PROVIDER);
+                throw new TransportError(PROVIDER, 'Pošta Slovenije tracking service is unavailable');
+            }
+            if (response.status === 403)
+                throw new ChallengeError(PROVIDER, 'Pošta Slovenije refused the app\'s guest lookup');
+            return parsePostaSlovenije(payload, number);
+        };
+        // A request that fails to reach Pošta Slovenije, or hangs, gets one more
+        // try: the first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'posta-slovenije', 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 PostaSlovenijeTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return {
+        id: 'posta-slovenije', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizePostaSlovenijeNumber(number))),
+    };
+};

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

@@ -18,18 +18,53 @@
   "timezone": "Europe/Ljubljana",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "posta-slovenije",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 790
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "delivered_at",
+    "pickup_point"
+  ],
   "portal": {
     "url": "https://moja.posta.si/tracking?trackingNumber={trackingNumber}",
     "searchUrl": "https://moja.posta.si/tracking",
     "canaryUrl": "https://moja.posta.si/tracking",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "postcodes"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code",
+      "delivered_at",
+      "pickup_point"
+    ],
+    "discarded": [
+      "postcodes",
+      "pickup_point_address",
+      "signatory",
+      "pickup_code"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "service_name",
+      "sender_name",
+      "proof_of_delivery"
+    ]
   },
   "links": [
     {
@@ -42,5 +77,13 @@
       ]
     }
   ],
-  "detection": []
+  "detection": [
+    {
+      "id": "posta-slovenije-s10",
+      "pattern": "^[A-Z]{2}\\d{9}SI$",
+      "confidence": "low",
+      "preferred": true,
+      "checksum": "s10"
+    }
+  ]
 }

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

@@ -67,13 +67,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try on 11 Oct 2026; it is not described as a live shipment."
+      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try. Pošta Slovenije's own tracking returns its history; detection selects the generic postal carrier."
     },
     {
       "number": "CF369007664SI",
@@ -86,13 +86,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try on 11 Oct 2026; it is not described as a live shipment."
+      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try. Pošta Slovenije's own tracking returns its history; detection selects the generic postal carrier."
     },
     {
       "number": "CF369340877SI",
@@ -105,13 +105,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try on 11 Oct 2026; it is not described as a live shipment."
+      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try. Pošta Slovenije's own tracking returns its history; detection selects the generic postal carrier."
     },
     {
       "number": "LH013496345SI",
@@ -143,13 +143,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "intl-post",
         "confidence": "high"
       },
-      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try on 11 Oct 2026; it is not described as a live shipment."
+      "note": "ParcelPanel's Slovenia Post page offered it as a sample to try. Pošta Slovenije's own tracking returns its history; detection selects the generic postal carrier."
     }
   ]
 }

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

@@ -0,0 +1,17 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Po\u0161ta Slovenije";
+export declare const POSTA_SLOVENIJE_MAX_BYTES = 512000;
+/**
+ * Pošta Slovenije tracks UPU S10 items: the ones it issues, which end in SI,
+ * and the ones other posts hand it to deliver.
+ */
+export declare function normalizePostaSlovenijeNumber(raw: string): string;
+/** The service's not-found reply names the number it looked for: "Record not found for Id '…'". */
+export declare function isNotFoundReply(payload: unknown, number: string): boolean;
+/**
+ * The guest lookup's reply for one number: the parcel and its scans, oldest
+ * first, each with a code, wording in Slovenian and English, a UTC clock and
+ * the post office it happened at. Sender, recipient, signatory, pickup codes
+ * and addresses are left out.
+ */
+export declare function parsePostaSlovenije(payload: unknown, rawNumber: string): CarrierResult;

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

@@ -0,0 +1,131 @@
+import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
+import { lastMovement } from '../../core/result/pickup.js';
+import { classifyWording, languageStageStatus } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { postaSlovenijeStage, startsReturn } from './status.js';
+export const PROVIDER = 'Pošta Slovenije';
+// A long history is a few kilobytes.
+export const POSTA_SLOVENIJE_MAX_BYTES = 512_000;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+const CODE = /^[A-Z0-9]{1,20}$/;
+// The unit type of a post office; a parcel locker is 8.
+const POST_OFFICE = 99;
+/**
+ * Pošta Slovenije tracks UPU S10 items: the ones it issues, which end in SI,
+ * and the ones other posts hand it to deliver.
+ */
+export function normalizePostaSlovenijeNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (isValidS10TrackingNumber(number))
+        return number;
+    throw new InvalidInputError(PROVIDER, 'Pošta Slovenije tracks S10 item codes');
+}
+/** The service's not-found reply names the number it looked for: "Record not found for Id '…'". */
+export function isNotFoundReply(payload, number) {
+    if (!isRecord(payload) || payload.errorCode !== 'error.not.found')
+        return false;
+    const named = /\bId '([^']*)'/.exec(clean(payload.errorMessage, 200))?.[1];
+    return named === undefined || named.trim().toUpperCase() === number;
+}
+/** The scan's English heading, its detail line and the next step after a failed delivery, as the tracker lists them. */
+function wordingOf(row) {
+    const parts = [clean(row.codeDescriptionEN, 300) || clean(row.codeDescriptionSI, 300),
+        clean(row.codeDetailedDescriptionEN, 300), clean(row.nondeliveryActionEN, 300)]
+        .map(part => part.replace(/[.\s]+$/, '')).filter(Boolean);
+    return [...new Set(parts)].join('. ');
+}
+/**
+ * The guest lookup's reply for one number: the parcel and its scans, oldest
+ * first, each with a code, wording in Slovenian and English, a UTC clock and
+ * the post office it happened at. Sender, recipient, signatory, pickup codes
+ * and addresses are left out.
+ */
+export function parsePostaSlovenije(payload, rawNumber) {
+    const number = normalizePostaSlovenijeNumber(rawNumber);
+    const result = isRecord(payload) ? payload.result : undefined;
+    if (!isRecord(result) || !isRecord(result.parcel))
+        throw new SchemaError(PROVIDER, 'Pošta Slovenije did not return a parcel');
+    const parcel = result.parcel;
+    if (typeof parcel.trackingNumber !== 'string' || parcel.trackingNumber.trim().toUpperCase() !== number) {
+        throw new SchemaError(PROVIDER, 'Pošta Slovenije answered for a different parcel');
+    }
+    const rows = result.statuses ?? [];
+    if (!Array.isArray(rows) || rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'Pošta Slovenije returned an invalid parcel history');
+    const scans = [];
+    const seen = new Set();
+    rows.forEach((row, index) => {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'Pošta Slovenije returned an invalid scan');
+        const code = clean(row.code, 40);
+        const at = explicitOffsetTime(row.statusDateTime);
+        if (!CODE.test(code) || !at)
+            throw new SchemaError(PROVIDER, 'Pošta Slovenije returned a scan without a code or clock');
+        // The post office's name; its number, a postcode, is left out.
+        const place = clean(row.postalName, 120);
+        const event = { time: at.iso, description: wordingOf(row) || code, provider_code: code, ...(place ? { location: place } : {}) };
+        const identity = JSON.stringify(event);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        scans.push({ event, at: at.timestamp, code, postOffice: row.unitType === POST_OFFICE, index });
+    });
+    // Newest first; scans at the same instant follow the reply's order, reversed.
+    scans.sort((left, right) => right.at - left.at || right.index - left.index);
+    // Oldest first: a delivery after the item was sent back reaches its sender.
+    let returning = false;
+    for (const scan of [...scans].reverse()) {
+        const description = scan.event.description;
+        const classified = postaSlovenijeStage(scan.code, description);
+        if (startsReturn(scan.code, description))
+            returning = true;
+        if (!classified)
+            continue;
+        const stage = classified.stage === 'delivered' && returning ? 'returned' : classified.stage;
+        Object.assign(scan.event, { stage, stage_source: classified.source });
+    }
+    const events = scans.map(scan => scan.event);
+    if (!scans.length)
+        return summaryOf(parcel);
+    const decider = scans[0];
+    const stage = decider.event.stage;
+    // The post office an item waits at is its pickup point. A delivered item
+    // was collected there when it waited there last before the delivery.
+    const earlier = scans.slice(1);
+    const waiting = stage === 'ready_for_pickup' ? decider
+        : stage === 'delivered' && lastMovement(earlier.map(scan => scan.event)) === 'ready_for_pickup'
+            ? earlier.find(scan => scan.event.stage === 'ready_for_pickup') : undefined;
+    const point = waiting?.postOffice ? waiting.event.location ?? '' : '';
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: decider.event.stage_source } : {}),
+        last_status_text: decider.event.description,
+        last_update: decider.event.time,
+        expected_delivery: null,
+        ...(stage === 'delivered' ? { delivered_at: decider.event.time } : {}),
+        ...(point ? { pickup_point: point } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}
+/** A parcel without scans: its own heading and the clock of its state. */
+function summaryOf(parcel) {
+    const wording = clean(parcel.codeDescriptionEN, 300) || clean(parcel.codeDescriptionSI, 300);
+    if (!wording)
+        throw new IndeterminateError(PROVIDER, 'Pošta Slovenije returned a parcel without a state or scans');
+    const classified = classifyWording(wording, 'in_transit');
+    const stage = classified.source === 'none' ? undefined : classified.stage;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: classified.source } : {}),
+        last_status_text: wording,
+        summary_only: true,
+        last_update: explicitOffsetTime(parcel.currentStatusDateTime)?.iso ?? null,
+        expected_delivery: null,
+        events: [],
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** Whether a scan sends the item back to its sender: a delivery after it reaches the sender. */
+export declare function startsReturn(code: string, wording: string): boolean;
+/** The stage the carrier's code gives a scan, if the map knows it. */
+export declare function postaSlovenijeCodeStage(code: string, wording: string): Stage | undefined;
+/**
+ * A scan's stage from its code, else from the shared rules for its English
+ * wording. Wording neither knows stays without a stage, so it remains visible.
+ */
+export declare function postaSlovenijeStage(code: string, wording: string): ClassifiedWording | null;
+/** Every scan carries a code; V reads its next step from the wording. */
+export declare const statusMap: CarrierStatusMap;

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

@@ -0,0 +1,56 @@
+import { classifyWording } from '../../core/status/index.js';
+/**
+ * Pošta Slovenije names each scan with a short code of its own, such as VL,
+ * and words it in Slovenian and English, with a detail line and, after a
+ * failed delivery, what happens next. The Slovenian wording is the more exact
+ * one, and the notes below follow it.
+ */
+const CODES = {
+    // The sender's data arrived; the item is not handed over yet.
+    NAJ: 'registered',
+    // The item arrived at Pošta Slovenije and was sent on.
+    S: 'accepted',
+    // "Pošiljka bo predvidoma dostavljena danes": with the postman, on its way to the address.
+    N: 'out_for_delivery',
+    // On its way to the parcel locker the recipient chose.
+    VLPAKP: 'out_for_delivery',
+    // Put in the recipient's letterbox or post office box, or handed over at the address.
+    VL: 'delivered',
+    // Nobody collected it from the parcel locker in time; it goes to a post office.
+    POTPKTM: 'failed_attempt',
+    // "Pošiljka ni bila prevzeta": not collected. What follows is in the scan's next step.
+    V: 'failed_attempt',
+    // It could not be delivered and goes to the post office, where it can be collected.
+    VDO: 'failed_attempt',
+    // Waiting at the post office for the recipient.
+    IZR: 'ready_for_pickup',
+    PVI: 'ready_for_pickup',
+};
+/** The next step a failed delivery names when the item goes back to its sender. */
+const RETURNING = /\breturned to the sender\b/i;
+/** Whether a scan sends the item back to its sender: a delivery after it reaches the sender. */
+export function startsReturn(code, wording) {
+    return code === 'V' && RETURNING.test(wording);
+}
+/** The stage the carrier's code gives a scan, if the map knows it. */
+export function postaSlovenijeCodeStage(code, wording) {
+    if (startsReturn(code, wording))
+        return 'exception';
+    return Object.hasOwn(CODES, code) ? CODES[code] : undefined;
+}
+/**
+ * A scan's stage from its code, else from the shared rules for its English
+ * wording. Wording neither knows stays without a stage, so it remains visible.
+ */
+export function postaSlovenijeStage(code, wording) {
+    const mapped = postaSlovenijeCodeStage(code, wording);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+/** Every scan carries a code; V reads its next step from the wording. */
+export const statusMap = {
+    stage: (code, wording) => (code ? postaSlovenijeCodeStage(code, wording) : undefined),
+    gaps: [],
+};

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

@@ -1,4 +1,16 @@
 {
   "carrier": "posta-slovenije",
-  "entries": []
+  "entries": [
+    { "code": "NAJ", "wording": "The item information has been received in the Pošta Slovenije system", "language": "en", "stage": "registered", "confirmedBy": "live", "note": "The sender's data arrived; the detail line says the item is not handed over yet." },
+    { "code": "S", "wording": "The item has arrived at Pošta Slovenije", "language": "en", "stage": "accepted", "confirmedBy": "live", "note": "Accepted at the post office or centre the scan names. Inbound items get it when they reach Slovenia." },
+    { "code": "N", "wording": "The item is expected to be delivered today", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live", "note": "Seen with the detail line \"The item is out for doorstep delivery\"." },
+    { "code": "VLPAKP", "wording": "The item is on its way to the selected parcel locker", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live" },
+    { "code": "VL", "wording": "The item was delivered to the mailbox / P.O. box", "language": "en", "stage": "delivered", "confirmedBy": "live", "note": "Seen with the detail line \"The item was delivered to the doorstep\". After an item was sent back, the adapter reads it as returned." },
+    { "code": "POTPKTM", "wording": "Unsuccessful delivery", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "note": "The Slovenian wording is more exact: nobody collected the item from the parcel locker in time." },
+    { "code": "V", "wording": "Unsuccessful delivery attempt", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "note": "Not collected. The next step follows, such as \"The item is ready for pickup at the post office\"." },
+    { "code": "V", "wording": "Unsuccessful delivery attempt. Item is being returned to the sender", "language": "en", "stage": "exception", "confirmedBy": "live", "note": "Not collected and sent back to the sender. A delivery after it reaches the sender." },
+    { "code": "VDO", "wording": "Unsuccessful delivery attempt", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "note": "Could not be delivered; seen with the next step \"The item will be redirected to the post office\"." },
+    { "code": "IZR", "wording": "The item is ready for pickup at the post office", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "note": "Its place names the post office the item waits at." },
+    { "code": "PVI", "wording": "The item is ready for pickup at the post office", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "note": "Its place names the post office the item waits at, after a failed delivery." }
+  ]
 }

package/dist/core/catalog/statusMaps.js

@@ -49,6 +49,7 @@ import { statusMap as oldDominion } from '../../carriers/old-dominion/status.js'
 import { statusMap as omgo } from '../../carriers/omgo/status.js';
 import { statusMap as omniva } from '../../carriers/omniva/status.js';
 import { statusMap as orlenPaczka } from '../../carriers/orlen-paczka/status.js';
+import { statusMap as postaSlovenije } from '../../carriers/posta-slovenije/status.js';
 import { statusMap as postlogistics } from '../../carriers/postlogistics/status.js';
 import { statusMap as ppl } from '../../carriers/ppl/status.js';
 import { statusMap as ptt } from '../../carriers/ptt/status.js';
@@ -75,7 +76,7 @@ export const STATUS_MAPS = {
     'dpd-fr': dpdFr, 'dpd-ie': dpdIe, 'dpd-pl': dpdPl, econt, elta, emile, 'express-one': expressOne, 'fan-courier': fanCourier, foxpost,
     'geniki-taxydromiki': geniki, 'gls-es': glsEs, 'gls-it': glsIt, 'gofo-fr': gofoFr, 'gofo-it': gofoIt, helthjem, 'j-and-t': jAndT,
     'j-and-t-cargo': jntCargo, 'la-poste': laPoste, matkahuolto, 'mng-kargo': mngKargo, 'old-dominion': oldDominion, omgo, omniva,
-    'orlen-paczka': orlenPaczka, postlogistics, ppl, ptt, sagawa, sameday, speedx, speedy, sto, 'swiss-post': swissPost, 'thailand-post': thailandPost,
+    'orlen-paczka': orlenPaczka, 'posta-slovenije': postaSlovenije, postlogistics, ppl, ptt, sagawa, sameday, speedx, speedy, sto, 'swiss-post': swissPost, 'thailand-post': thailandPost,
     tnt, ups, venipak, 'vinted-go': vintedGo, yunexpress, 'yurtici-kargo': yurticiKargo,
 };
 /** The carrier the app files the universal providers' scans under. */

package/dist/data/catalog.json

@@ -7590,7 +7590,8 @@
         "timezone": "Europe/Ljubljana",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "posta-slovenije",
+            "recognitionRank": 790
         },
         "canaryUrl": "https://moja.posta.si/tracking",
         "trackingUrlTemplate": "https://moja.posta.si/tracking?trackingNumber={trackingNumber}",
@@ -7606,7 +7607,14 @@
                 ]
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}SI$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "posta-srbije": {
         "displayName": "Pošta Srbije",

package/dist/generated/catalog.d.ts

@@ -5104,7 +5104,8 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Europe/Ljubljana";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "posta-slovenije";
+            readonly recognitionRank: 790;
         };
         readonly canaryUrl: "https://moja.posta.si/tracking";
         readonly trackingUrlTemplate: "https://moja.posta.si/tracking?trackingNumber={trackingNumber}";
@@ -5114,7 +5115,12 @@ export declare const CARRIER_CATALOG: {
             readonly pathPattern: "^/tracking/?$";
             readonly params: readonly ["trackingNumber"];
         }];
-        readonly detectionRules: readonly [];
+        readonly detectionRules: readonly [{
+            readonly pattern: "^[A-Z]{2}\\d{9}SI$";
+            readonly confidence: "low";
+            readonly checksum: "s10";
+            readonly preferred: true;
+        }];
     };
     readonly "posta-srbije": {
         readonly displayName: "Pošta Srbije";

package/dist/generated/catalog.js

@@ -7591,7 +7591,8 @@ export const CARRIER_CATALOG = {
         "timezone": "Europe/Ljubljana",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "posta-slovenije",
+            "recognitionRank": 790
         },
         "canaryUrl": "https://moja.posta.si/tracking",
         "trackingUrlTemplate": "https://moja.posta.si/tracking?trackingNumber={trackingNumber}",
@@ -7607,7 +7608,14 @@ export const CARRIER_CATALOG = {
                 ]
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}SI$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "posta-srbije": {
         "displayName": "Pošta Srbije",
@@ -8911,7 +8919,7 @@ export const DETECTION_RULE_IDS = {
     "paquetexpress": [],
     "passport": ["passport-1"],
     "post-luxembourg": [],
-    "posta-slovenije": [],
+    "posta-slovenije": ["posta-slovenije-s10"],
     "posta-srbije": [],
     "ppl": [],
     "ptt": ["ptt-1", "ptt-s10"],

package/dist/generated/recognition.js

@@ -60,6 +60,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "ontrac": 210,
     "orlen-paczka": 490,
     "poczta-polska": 310,
+    "posta-slovenije": 790,
     "poste-italiane": 460,
     "posti": 270,
     "postlogistics": 260,

package/dist/generated/registry.js

@@ -106,6 +106,7 @@ import { adapter as packeta } from '../carriers/packeta/adapter.js';
 import { adapter as planzer } from '../carriers/planzer/adapter.js';
 import { adapter as pocztaPolska } from '../carriers/poczta-polska/adapter.js';
 import { adapter as posMalaysia } from '../carriers/pos-malaysia/adapter.js';
+import { adapter as postaSlovenije } from '../carriers/posta-slovenije/adapter.js';
 import { adapter as posteItaliane } from '../carriers/poste-italiane/adapter.js';
 import { adapter as posti } from '../carriers/posti/adapter.js';
 import { adapter as postlogistics } from '../carriers/postlogistics/adapter.js';
@@ -256,6 +257,7 @@ export const REGISTRY = {
         "planzer": planzer,
         "poczta-polska": pocztaPolska,
         "pos-malaysia": posMalaysia,
+        "posta-slovenije": postaSlovenije,
         "poste-italiane": posteItaliane,
         "posti": posti,
         "postlogistics": postlogistics,
@@ -446,7 +448,7 @@ export const REGISTRY = {
         "poczta-polska": "poczta-polska",
         "pos-malaysia": "pos-malaysia",
         "post-luxembourg": "universal",
-        "posta-slovenije": "universal",
+        "posta-slovenije": "posta-slovenije",
         "posta-srbije": "universal",
         "poste-italiane": "poste-italiane",
         "posti": "posti",

package/dist/server/openapi.json

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

package/package.json

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