universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/planzer/statuses.json

@@ -0,0 +1,229 @@
+{
+  "carrier": "planzer",
+  "entries": [
+    {
+      "wording": "Recorded",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "Transferred",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "In delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "Shipped",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": "Planzer's English label for delivered (Zugestellt / Livré), never dispatched; stored and shown as \"Delivered\"."
+    },
+    {
+      "wording": "Shipment on the way",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Shipment out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Shipment delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Not delivered",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Not delivered – A delivery card has been deposited",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-27",
+      "note": "German \"Nicht zugestellt - Zustellkarte hinterlassen\"."
+    },
+    {
+      "wording": "New delivery released",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-27",
+      "note": "German \"Erneute Zustellung ausgelöst\": a redelivery was booked after a failed attempt."
+    },
+    {
+      "wording": "enregistré",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "erfasst",
+      "language": "de",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "registrato",
+      "language": "it",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "transféré",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "weitergeleitet",
+      "language": "de",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "inoltrato",
+      "language": "it",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "en cours de livraison",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "in zustellung",
+      "language": "de",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "in consegna",
+      "language": "it",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "livré",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "zugestellt",
+      "language": "de",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "consegnato",
+      "language": "it",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "Erfasst",
+      "language": "de",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"recorded\", \"enregistr\" and \"registrat\"."
+    },
+    {
+      "wording": "Abholung",
+      "language": "de",
+      "stage": "accepted",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"collection\", \"collecte\" and \"ritiro\"."
+    },
+    {
+      "wording": "Umschlaglager",
+      "language": "de",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"transfer depot\", \"transshipment\", \"plateforme\" and \"trasbordo\"."
+    },
+    {
+      "wording": "In Auslieferung",
+      "language": "de",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"out for delivery\", \"en livraison\" and \"in consegna\"."
+    },
+    {
+      "wording": "Ausgeliefert",
+      "language": "de",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"delivered\", \"livré\", \"livrée\" and \"consegnat\"."
+    }
+  ]
+}

package/dist/carriers/poczta-polska/adapter.d.ts

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

package/dist/carriers/poczta-polska/adapter.js

@@ -0,0 +1,65 @@
+import { load } from 'cheerio';
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { normalizePocztaPolskaNumber, parsePocztaPolska } from './parser.js';
+const PORTAL = 'https://emonitoring.poczta-polska.pl/';
+const BASE = 'https://uss.poczta-polska.pl/uss/v2.0/tracking';
+export function parsePocztaPolskaBootstrap(html) {
+    const widgets = load(html)('#widgetTracking');
+    const endpoint = widgets.attr('data-urltracking');
+    const apiKey = widgets.attr('data-apikey');
+    if (widgets.length !== 1 || endpoint !== BASE || !apiKey || apiKey.length < 20 || apiKey.length > 4096 || /\s/.test(apiKey)) {
+        throw new SchemaError('poczta-polska', 'Poczta Polska tracking configuration changed');
+    }
+    return { endpoint, apiKey };
+}
+export class PocztaPolskaTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizePocztaPolskaNumber(raw);
+        return runSteps({ carrier: 'poczta-polska', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const started = performance.now();
+                    const bounded = async (url, init, maxBytes) => {
+                        signal.throwIfAborted();
+                        try {
+                            return await fetchBounded(url, { ...init, signal }, { provider: 'poczta-polska',
+                                timeoutMs: Math.max(1, Math.floor(remainingMs - (performance.now() - started))),
+                                maxBytes, fetcher: this.options.fetcher });
+                        }
+                        catch (error) {
+                            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                                throw new TransportError('poczta-polska', 'Poczta Polska tracking endpoint is unavailable', { cause: error });
+                            }
+                            throw error;
+                        }
+                    };
+                    // This key is anonymous widget configuration published on the portal,
+                    // not an issued account credential. Read it fresh instead of storing it.
+                    const { bytes: html } = await bounded(PORTAL, { headers: { Accept: 'text/html' } }, 500_000);
+                    const { endpoint, apiKey } = parsePocztaPolskaBootstrap(decodeText(html));
+                    const { bytes } = await bounded(`${endpoint}/checkmailex`, { method: 'POST', headers: {
+                            Accept: 'application/json', 'Content-Type': 'application/json', API_KEY: apiKey,
+                        }, body: JSON.stringify({ language: 'EN', number, addPostOfficeInfo: false }) }, 1_000_000);
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'poczta-polska');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('poczta-polska', 'Poczta Polska returned invalid tracking JSON', { cause });
+                    }
+                    return parsePocztaPolska(payload, raw);
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new PocztaPolskaTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'poczta-polska', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizePocztaPolskaNumber(number))) };
+};

package/dist/carriers/poczta-polska/carrier.json

@@ -0,0 +1,79 @@
+{
+  "id": "poczta-polska",
+  "displayName": "Poczta Polska",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "PL"
+    ]
+  },
+  "brand": {
+    "color": "#c43c2b"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "poczta-polska",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 31
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "weight"
+  ],
+  "portal": {
+    "url": "https://emonitoring.poczta-polska.pl/?lang=en&numer={trackingNumber}",
+    "canaryUrl": "https://emonitoring.poczta-polska.pl/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "weight"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "weight"
+    ],
+    "discarded": [
+      "office_addresses",
+      "office_opening_hours",
+      "payment_documents",
+      "additional_services"
+    ],
+    "unavailable": [
+      "eta",
+      "offset_timestamps"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "emonitoring.poczta-polska.pl"
+      ],
+      "params": [
+        "numer"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "poczta-polska-1",
+      "pattern": "^\\d{19,20}$",
+      "confidence": "low"
+    },
+    {
+      "id": "poczta-polska-2",
+      "pattern": "^PX\\d{10}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/poczta-polska/numbers.json

@@ -0,0 +1,130 @@
+{
+  "carrier": "poczta-polska",
+  "records": [
+    {
+      "number": "0015900773312345678",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "poczta-polska"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to Poczta Polska, which stays one candidate among several."
+    },
+    {
+      "number": "CP265970733PL",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.chinapostaltracking.com/qa/blocked-since-july-161167/",
+        "date": "2026-09-22"
+      },
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Poczta Polska; detection selects the generic postal carrier. Sent from Poland to China; the page does not name the carrier."
+    },
+    {
+      "number": "PX0000000013",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "expect": {
+        "carrier": "poczta-polska",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "PX7678676761",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aa57c3bf5ad63b0c0d968f3",
+        "date": "2026-09-12"
+      },
+      "expect": {
+        "carrier": "poczta-polska",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Pocztex parcel."
+    },
+    {
+      "number": "CP123456789PL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to Poczta Polska, which no rule claims."
+    },
+    {
+      "number": "EE123456789PL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to Poczta Polska, which no rule claims."
+    },
+    {
+      "number": "RR123456789PL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to Poczta Polska, which no rule claims."
+    },
+    {
+      "number": "VV123456789PL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.poczta-polska.pl/en/sledzenie-przesylek/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to Poczta Polska, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/poczta-polska/parser.d.ts

@@ -0,0 +1,3 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizePocztaPolskaNumber(raw: string): string;
+export declare function parsePocztaPolska(payload: unknown, number: string): CarrierResult;

package/dist/carriers/poczta-polska/parser.js

@@ -0,0 +1,96 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyPocztaPolskaStatus } from './status.js';
+export function normalizePocztaPolskaNumber(raw) {
+    const number = raw.toUpperCase().replace(/\s/g, '');
+    if (!/^(?:\d{19,20}|PX\d{10})$/.test(number) && !isValidS10TrackingNumber(number)) {
+        throw new TypeError('Poczta Polska requires a parcel barcode or valid postal tracking number');
+    }
+    if (number.length !== 19)
+        return number;
+    // The official widget appends the GS1 check digit to a 19-digit reference
+    // before submitting it. The JSON service itself does not resolve that alias.
+    const sum = [...number].reduce((total, digit, index) => total + Number(digit) * (index % 2 ? 1 : 3), 0);
+    return `${number}${(10 - sum % 10) % 10}`;
+}
+function eventClock(value) {
+    if (value != null && typeof value !== 'string')
+        throw new SchemaError('poczta-polska', 'Poczta Polska returned an invalid clock field');
+    const raw = clean(value, 64);
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/i.test(raw)) {
+        const parsed = explicitOffsetTime(raw);
+        if (parsed)
+            return { time: parsed.iso };
+    }
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?$/.test(raw)) {
+        // UTC validates the calendar only. It is never attached to local digits.
+        const parsed = DateTime.fromISO(raw, { zone: 'UTC' });
+        const local = parsed.isValid ? parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) : null;
+        if (local)
+            return { local_time: local };
+    }
+    return raw ? { provider_time_text: raw } : {};
+}
+export function parsePocztaPolska(payload, number) {
+    const requested = normalizePocztaPolskaNumber(number);
+    if (!isRecord(payload) || !Number.isInteger(payload.mailStatus) || typeof payload.number !== 'string'
+        || payload.number.trim().toUpperCase() !== requested)
+        throw new SchemaError('poczta-polska', 'Poczta Polska returned an invalid parcel envelope');
+    if (payload.mailStatus === -1 && !Object.hasOwn(payload, 'mailInfo'))
+        throw new NotFoundError('poczta-polska');
+    if (payload.mailStatus !== 0)
+        throw new IndeterminateError('poczta-polska', 'Poczta Polska returned an ambiguous or incomplete parcel result');
+    const item = payload.mailInfo;
+    if (!isRecord(item) || typeof item.number !== 'string' || item.number.trim().toUpperCase() !== requested
+        || !Array.isArray(item.events) || item.events.length > 500)
+        throw new SchemaError('poczta-polska');
+    if (item.components != null && (!Array.isArray(item.components) || item.components.length > 100
+        || !item.components.every(component => typeof component === 'string' && component.trim().length > 0 && component.length <= 80))) {
+        throw new SchemaError('poczta-polska', 'Poczta Polska returned an invalid component list');
+    }
+    if (item.typeOfMailCode === 'PPL' || (Array.isArray(item.components) && item.components.length > 0)) {
+        throw new IndeterminateError('poczta-polska', 'Poczta Polska grouped consignments require parcel-level history');
+    }
+    const projected = item.events.map((raw) => {
+        if (!isRecord(raw))
+            throw new SchemaError('poczta-polska');
+        if (raw.canceled === true)
+            throw new IndeterminateError('poczta-polska', 'Poczta Polska returned an invalidated scan');
+        const description = clean(raw.name, 500);
+        const code = clean(raw.code, 40);
+        if (!description || !code)
+            throw new SchemaError('poczta-polska', 'Poczta Polska returned an incomplete scan');
+        const location = isRecord(raw.postOffice) ? clean(raw.postOffice.name, 160) : '';
+        const mapped = classifyPocztaPolskaStatus(code);
+        return { ...eventClock(raw.time), description, provider_code: code,
+            ...(location ? { location } : {}), ...(mapped ? { stage: mapped.stage } : {}) };
+    });
+    if (!projected.length)
+        throw new IndeterminateError('poczta-polska', 'Poczta Polska returned no parcel history');
+    // The widget's last source row is current. Do not compare offsetless wall
+    // clocks from different countries or move malformed clocks behind old scans.
+    projected.reverse();
+    if (projected.every(event => event.time))
+        projected.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const seen = new Set();
+    const events = projected.filter(event => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const latest = events[0];
+    const current = classifyPocztaPolskaStatus(latest.provider_code);
+    const weight = item.weight;
+    return { status: current?.status ?? 'unknown', ...(current ? { current_stage: current.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null,
+        ...(latest.local_time ? { last_update_local: latest.local_time } : {}), expected_delivery: null,
+        ...(typeof weight === 'number' && Number.isFinite(weight) && weight > 0 ? { weight_kg: weight } : {}),
+        ...(number.toUpperCase().replace(/\s/g, '') !== requested ? { canonical_tracking_number: requested } : {}),
+        events: events.slice(0, 100) };
+}

package/dist/carriers/poczta-polska/status.d.ts

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function classifyPocztaPolskaStatus(code: string): ClassifiedStatus | undefined;

package/dist/carriers/poczta-polska/status.js

@@ -0,0 +1,21 @@
+// The specific scan code takes precedence over its broader state label: an
+// unsuccessful delivery can still carry the state DOR (in delivery).
+const CODES = {
+    P_REJ_KN1: { status: 'pending', stage: 'registered' },
+    P_NAD: { status: 'in_transit', stage: 'accepted' },
+    P_PZL: { status: 'in_transit', stage: 'in_transit' },
+    P_WZL: { status: 'in_transit', stage: 'in_transit' },
+    P_WEOC: { status: 'in_transit', stage: 'in_transit' },
+    P_WYPL: { status: 'in_transit', stage: 'in_transit' },
+    P_WD: { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    P_D: { status: 'delivered', stage: 'delivered' },
+};
+const FAILED_DELIVERY = new Set(['P_ND', 'P_NDZ', 'P_NDZK', 'P_NDPD', 'P_R',
+    'P_NDZAP', 'P_NDZKON', 'P_ZDUN', 'P_CZDKN', 'P_NDPJ']);
+export function classifyPocztaPolskaStatus(code) {
+    if (Object.hasOwn(CODES, code))
+        return CODES[code];
+    if (FAILED_DELIVERY.has(code))
+        return { status: 'exception', stage: 'exception' };
+    return undefined;
+}