universal-parcel-scraper 0.74.0-main.925 → 0.75.0-main.929

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 **129 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **130 dedicated adapters** and **5 universal fallbacks**
 
 <sub>207 catalog entries · 66 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 3,613 such statuses, each filed under one stage.
+The carrier folders record 3,675 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

@@ -7462,7 +7462,7 @@
     "timezone": "Europe/Prague",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "ppl"
     },
     "canaryUrl": "https://www.ppl.cz/vyhledat-zasilku",
     "trackingUrlTemplate": "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}",

package/data/coverage-summary.json

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

package/dist/browser/scraper.js

@@ -5917,7 +5917,7 @@ var ye = {
 		timezone: "Europe/Prague",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "ppl"
 		},
 		canaryUrl: "https://www.ppl.cz/vyhledat-zasilku",
 		trackingUrlTemplate: "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}",

package/dist/carriers/mrw/status.js

@@ -9,6 +9,16 @@ const LABELS = {
     'DEPOSITADO EN PUNTO MRW': { status: 'in_transit', stage: 'ready_for_pickup' },
     'DEPOSITADO EN POINTCORNER DESTINO': { status: 'in_transit', stage: 'ready_for_pickup' },
     'ENVIO ENTREGADO': { status: 'delivered', stage: 'delivered' },
+    // www.mrw.pt renders the same history in Portuguese.
+    'PENDENTE DE RECOLHER': { status: 'pending', stage: 'registered' },
+    'ENVIO RECOLHIDO NA ORIGEM': { status: 'in_transit', stage: 'accepted' },
+    'EM TRANSITO': { status: 'in_transit', stage: 'in_transit' },
+    'ENVIO EM DISTRIBUICAO': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'DESTINATARIO AUSENTE OU FECHADO': { status: 'exception', stage: 'failed_attempt' },
+    'ACORDADA PROXIMA ENTREGA': { status: 'in_transit', stage: 'in_transit' },
+    'DEPOSITADO EM MRW POINT': { status: 'in_transit', stage: 'ready_for_pickup' },
+    'DEPOSITADO NO POINTCORNER DESTINO': { status: 'in_transit', stage: 'ready_for_pickup' },
+    'ENVIO ENTREGUE': { status: 'delivered', stage: 'delivered' },
 };
 export function classifyMrwStatus(value) {
     const key = value.normalize('NFD').replace(/\p{Diacritic}/gu, '').toUpperCase().replace(/\s+/g, ' ').trim();

package/dist/carriers/mrw/statuses.json

@@ -9,6 +9,15 @@
     { "wording": "Entrega concertada", "language": "es", "stage": "in_transit", "confirmedBy": "live" },
     { "wording": "Depositado en punto MRW", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "live" },
     { "wording": "Depositado en PointCorner destino", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "live" },
-    { "wording": "Envío entregado", "language": "es", "stage": "delivered", "confirmedBy": "live" }
+    { "wording": "Envío entregado", "language": "es", "stage": "delivered", "confirmedBy": "live" },
+    { "wording": "Pendente de recolher", "language": "pt", "stage": "registered", "confirmedBy": "live" },
+    { "wording": "Envio recolhido na origem", "language": "pt", "stage": "accepted", "confirmedBy": "live" },
+    { "wording": "Em tránsito", "language": "pt", "stage": "in_transit", "confirmedBy": "live" },
+    { "wording": "Envio em distribuição", "language": "pt", "stage": "out_for_delivery", "confirmedBy": "live" },
+    { "wording": "Destinatário ausente ou fechado", "language": "pt", "stage": "failed_attempt", "confirmedBy": "live" },
+    { "wording": "Acordada próxima entrega", "language": "pt", "stage": "in_transit", "confirmedBy": "live" },
+    { "wording": "Depositado em MRW Point", "language": "pt", "stage": "ready_for_pickup", "confirmedBy": "live" },
+    { "wording": "Depositado no PointCorner destino", "language": "pt", "stage": "ready_for_pickup", "confirmedBy": "live" },
+    { "wording": "Envio entregue", "language": "pt", "stage": "delivered", "confirmedBy": "live" }
   ]
 }

package/dist/carriers/ppl/adapter.d.ts

@@ -0,0 +1,15 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class PplTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+        /** The tracking page's key. Omit for the included one; null or blank turns the lookup off. */
+        key?: string | null;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/ppl/adapter.js

@@ -0,0 +1,49 @@
+import { ChallengeError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { normalizePplNumber, parsePpl, parsePplRejection, PPL } from './parser.js';
+const API = 'https://api.dhl.com/ecs/ppl/webapi/TrackAndTrace';
+/** The key PPL's tracking page gives every visitor, included with the maintainer's approval. */
+const KEY = '7HH634Q79Zpge4xEGeFAHXAnUMRxv0XQ';
+function json(bytes) {
+    const text = decodeText(bytes).replace(/^\uFEFF/, '');
+    if (/^\s*</.test(text))
+        throw new ChallengeError(PPL, 'PPL answered with a web page');
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new SchemaError(PPL, 'PPL returned invalid tracking JSON', { cause });
+    }
+}
+export class PplTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizePplNumber(raw);
+        const key = (this.options.key === undefined ? KEY : this.options.key ?? '').trim();
+        if (!key)
+            throw new ChallengeError(PPL, 'PPL tracking key is disabled');
+        return runSteps({ carrier: 'ppl', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    // The tracking page's own search: a POST with an empty body. English wording.
+                    const { response, bytes } = await fetchBounded(`${API}/${number}`, { method: 'POST', signal, headers: {
+                            Accept: 'application/json', 'Accept-Language': 'en-US', 'Content-Type': 'application/json', 'dhl-api-key': key,
+                            'User-Agent': userAgentOf(this.options.userAgent),
+                        }, body: '{}' }, { provider: PPL, timeoutMs: remainingMs, maxBytes: 1_000_000, fetcher: this.options.fetcher,
+                        allowHttpStatuses: [400, 404, 410] });
+                    if (response.status === 404 || response.status === 410)
+                        throw new TransportError(PPL, 'PPL tracking service is unavailable');
+                    const payload = json(bytes);
+                    return response.status === 400 ? parsePplRejection(payload, number) : parsePpl(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new PplTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent,
+        key: environment.env.PPL_TRACKING_KEY });
+    return { id: 'ppl', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/ppl/carrier.json

@@ -16,18 +16,60 @@
   "timezone": "Europe/Prague",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "ppl",
+    "steps": [
+      "direct"
+    ]
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "provider_code",
+    "eta",
+    "weight",
+    "delivered_at",
+    "pickup_point"
+  ],
   "portal": {
     "url": "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}",
     "searchUrl": "https://www.ppl.cz/vyhledat-zasilku",
     "canaryUrl": "https://www.ppl.cz/vyhledat-zasilku",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "eta",
+      "eta_window",
+      "weight",
+      "sender_name",
+      "customer_reference",
+      "pickup_point",
+      "pickup_point_address",
+      "delivery_partner",
+      "delivery_partner_reference",
+      "payment_details",
+      "proof_of_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "provider_code",
+      "eta",
+      "weight",
+      "delivered_at",
+      "pickup_point"
+    ],
+    "discarded": [
+      "eta_window",
+      "sender_name",
+      "customer_reference",
+      "pickup_point_address",
+      "delivery_partner",
+      "delivery_partner_reference",
+      "payment_details",
+      "proof_of_delivery"
+    ],
+    "unavailable": [
+      "location"
+    ]
   },
   "links": [
     {

package/dist/carriers/ppl/parser.d.ts

@@ -0,0 +1,10 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PPL = "PPL";
+export declare function normalizePplNumber(raw: string): string;
+/**
+ * The tracking service's HTTP 400 problem reply. Only its shipment-not-found
+ * detail, for the requested number when it names one, means PPL does not know
+ * the parcel; any other rejection proves nothing.
+ */
+export declare function parsePplRejection(payload: unknown, rawNumber: string): never;
+export declare function parsePpl(payload: unknown, rawNumber: string): CarrierResult;

package/dist/carriers/ppl/parser.js

@@ -0,0 +1,109 @@
+import { normalizeTrackingNumber } from '../../core/detection/normalize.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/text.js';
+import { isRecord } from '../../core/types.js';
+import { pplStage } from './status.js';
+export const PPL = 'PPL';
+const NOT_FOUND = 'service.TrackAndTrace.ShipmentNotFound';
+const MAX_SCANS = 500;
+const SETTLED = new Set(['delivered', 'returned', 'ready_for_pickup']);
+export function normalizePplNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^\d{11}$/.test(number))
+        throw new InvalidInputError(PPL, 'PPL requires an eleven-digit parcel number');
+    return number;
+}
+/**
+ * The tracking service's HTTP 400 problem reply. Only its shipment-not-found
+ * detail, for the requested number when it names one, means PPL does not know
+ * the parcel; any other rejection proves nothing.
+ */
+export function parsePplRejection(payload, rawNumber) {
+    const number = normalizePplNumber(rawNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PPL, 'PPL returned an invalid error reply');
+    if (payload.instance != null && payload.instance !== `/TrackAndTrace/${number}`) {
+        throw new SchemaError(PPL, 'PPL answered for another parcel');
+    }
+    if (payload.detail === NOT_FOUND)
+        throw new NotFoundError(PPL);
+    throw new IndeterminateError(PPL, 'PPL rejected the tracking request');
+}
+function scan(row) {
+    if (!isRecord(row))
+        throw new SchemaError(PPL, 'PPL returned an invalid scan');
+    const code = clean(row.code, 100);
+    const description = clean(row.eventText, 500);
+    if (!code || !description)
+        throw new SchemaError(PPL, 'PPL returned a scan without its code or wording');
+    // Scan clocks carry an explicit offset; one without stays unresolved text.
+    const time = explicitOffsetTime(row.eventDate);
+    const text = time ? '' : clean(row.eventDate, 64);
+    const stage = pplStage(code);
+    return { timestamp: time?.timestamp ?? null, ...(stage ? { stage } : {}), event: {
+            description, provider_code: code, ...(time ? { time: time.iso } : text ? { provider_time_text: text } : {}),
+            ...(stage ? { stage, stage_source: 'carrier_map' } : {}),
+        } };
+}
+/** The expected delivery day, only while the portal itself shows one and the parcel is still on its way. */
+function estimatedDay(payload, stage, latest) {
+    if (payload.showDeliveryDate !== true || !stage || SETTLED.has(stage))
+        return null;
+    const estimate = explicitOffsetTime(payload.expectedDeliveryDate);
+    if (!estimate)
+        return null;
+    const day = estimate.iso.slice(0, 10);
+    return typeof latest.time === 'string' && day < latest.time.slice(0, 10) ? null : day;
+}
+export function parsePpl(payload, rawNumber) {
+    const number = normalizePplNumber(rawNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PPL);
+    if (typeof payload.shipmentId !== 'string' || payload.shipmentId.trim() !== number) {
+        throw new SchemaError(PPL, 'PPL returned a different parcel');
+    }
+    const rows = payload.events;
+    if (!Array.isArray(rows) || rows.length > MAX_SCANS)
+        throw new SchemaError(PPL, 'PPL returned an invalid scan list');
+    if (!rows.length)
+        throw new IndeterminateError(PPL, 'PPL returned no parcel history');
+    // The service lists scans oldest first. Newest first, by instant when every
+    // scan has one; otherwise in the service's order.
+    const parsed = rows.map(scan).reverse();
+    if (parsed.every(item => item.timestamp !== null))
+        parsed.sort((left, right) => right.timestamp - left.timestamp);
+    const seen = new Set();
+    const scans = parsed.filter(item => {
+        const key = JSON.stringify(item.event);
+        return seen.has(key) ? false : (seen.add(key), true);
+    });
+    const events = scans.map(item => item.event);
+    const latest = events[0];
+    // Payment steps and codes the map does not know leave the last milestone in place.
+    const staged = scans.filter(item => item.stage);
+    const newest = staged[0]?.stage;
+    // From a return scan on, the parcel travels back and cannot be delivered
+    // again: a later delivery hands it to its sender.
+    const stage = newest && staged.some(item => item.stage === 'returned') ? 'returned' : newest;
+    const delivery = stage === 'delivered' ? staged.findIndex(item => item.stage === 'delivered') : -1;
+    // A ParcelShop or ParcelBox holds the parcel, or held it until the delivery
+    // that followed: the recipient collected it there. Its name only.
+    const held = stage === 'ready_for_pickup' || (delivery >= 0 && staged[delivery + 1]?.stage === 'ready_for_pickup');
+    const point = held && isRecord(payload.accessPoint) ? clean(payload.accessPoint.name, 160) : '';
+    const deliveredAt = delivery >= 0 ? staged[delivery].event.time : undefined;
+    const weight = payload.weight;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: 'carrier_map' } : {}),
+        last_status_text: latest.description ?? null,
+        last_update: latest.time ?? null,
+        expected_delivery: estimatedDay(payload, stage, latest),
+        ...(typeof deliveredAt === 'string' ? { delivered_at: deliveredAt } : {}),
+        ...(typeof weight === 'number' && Number.isFinite(weight) && weight > 0 && weight < 10_000 ? { weight_kg: weight } : {}),
+        ...(point ? { pickup_point: point } : {}),
+        ...(events.length > 100 ? { history_truncated: true } : {}),
+        events: events.slice(0, 100),
+    };
+}

package/dist/carriers/ppl/status.d.ts

@@ -0,0 +1,5 @@
+import type { Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage of one PPL event code, or undefined for a payment step or a code the map does not know. */
+export declare function pplStage(code: string): Stage | undefined;
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/ppl/status.js

@@ -0,0 +1,14 @@
+import statuses from './statuses.json' with { type: 'json' };
+// Every scan of PPL's tracking service carries an event code, and the code
+// alone decides the stage. The wording follows the requested language and
+// several codes share one wording, so it is never read. Entries without a
+// stage are cash-on-delivery payment steps: they move nothing.
+const CODES = new Map(statuses.entries.flatMap(entry => entry.stage ? [[entry.code, entry.stage]] : []));
+/** The stage of one PPL event code, or undefined for a payment step or a code the map does not know. */
+export function pplStage(code) {
+    return CODES.get(code);
+}
+export const statusMap = {
+    stage: code => code ? pplStage(code) : undefined,
+    gaps: statuses.entries.flatMap(entry => entry.stage ? [] : [{ code: entry.code, note: entry.note }]),
+};

package/dist/carriers/ppl/statuses.json

@@ -1,4 +1,58 @@
 {
   "carrier": "ppl",
-  "entries": []
+  "entries": [
+    {"code": "WaitingForShipment", "wording": "We are waiting for the shipment to be accepted for transport", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "The sender has created the label; PPL does not have the parcel yet."},
+    {"code": "WaitingForShipment.Foreign", "wording": "We are waiting for the shipment to be accepted for transport", "language": "en", "stage": "registered", "confirmedBy": "bundle", "note": "The portal's longer text adds that the parcel may be on its way from abroad."},
+    {"code": "WaitingForShipment.ExpiringLabel", "stage": "registered", "confirmedBy": "bundle", "note": "The portal shows the date the unused label expires with it. Its wording was not seen."},
+    {"code": "ShipmentInTransport.TakeOverFromSender", "wording": "We have received the shipment from the sender", "language": "en", "stage": "accepted", "confirmedBy": "live", "firstSeen": "2026-10-11"},
+    {"code": "ShipmentInTransport.TakeOverFromSender.WithException", "wording": "We have received the shipment from the sender", "language": "en", "stage": "accepted", "confirmedBy": "bundle", "note": "An acceptance with a remark; the portal words it as a plain acceptance."},
+    {"code": "PhysicalScan", "wording": "We have received the shipment from the sender", "language": "en", "stage": "accepted", "confirmedBy": "bundle", "note": "The portal words it as the acceptance from the sender."},
+    {"code": "ShipmentInTransport.TakeOverFromForeignPartner", "wording": "We have received the shipment from the foreign partner", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "PPL takes the parcel over from a partner abroad; the sender handed it over earlier."},
+    {"code": "ShipmentInForeignCountry", "wording": "The shipment is being transported to the destination", "language": "en", "stage": "in_transit", "confirmedBy": "bundle"},
+    {"code": "ShipmentInTransport", "wording": "The shipment is in transit", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-11"},
+    {"code": "PreparingForDelivery", "wording": "The shipment is in transit", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "Worded like ShipmentInTransport; the portal's longer text says the parcel is being prepared for delivery."},
+    {"code": "OtherDepot", "wording": "The shipment is in transit", "language": "en", "stage": "in_transit", "confirmedBy": "bundle"},
+    {"code": "HandedOverToForeignPartner", "wording": "The shipment has been handed over to a foreign partner for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "A partner abroad delivers the parcel, and PPL relays the partner's milestones after it."},
+    {"code": "HandedOverToDHLFreight", "wording": "The shipment was handed over to DHL Freight for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "The parcel exceeds parcel limits and DHL Freight delivers it."},
+    {"code": "InputDepot.Foreign", "wording": "The shipment is at the entry sorting hub abroad", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-11"},
+    {"code": "DeliveryToDepot.Foreign", "wording": "The shipment is on its way to the delivery depot at the destination", "language": "en", "stage": "in_transit", "confirmedBy": "bundle"},
+    {"code": "DeliveryDepot.Foreign", "wording": "The shipment is at the delivery depot at the destination", "language": "en", "stage": "in_transit", "confirmedBy": "bundle"},
+    {"code": "ExitDepot.Foreign", "wording": "The shipment is at the delivery depot at the destination", "language": "en", "stage": "in_transit", "confirmedBy": "bundle"},
+    {"code": "Undelivered.DidNotManage", "wording": "The shipment was not delivered due to lack of time", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "A delay on PPL's side, such as the driver running out of time: nobody tried the recipient, and a later round delivers the parcel."},
+    {"code": "Undelivered.WasNotReached", "wording": "The shipment was not delivered due to lack of time", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "A delay on PPL's side, such as the driver running out of time: nobody tried the recipient, and a later round delivers the parcel. Despite its code, the portal words it as a lack of time."},
+    {"code": "Undelivered.LackOfTime", "wording": "The shipment was not delivered due to the late arrival of shipments at the delivery depot", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "A delay on PPL's side, such as the driver running out of time: nobody tried the recipient, and a later round delivers the parcel."},
+    {"code": "Undelivered.CarFault", "wording": "The shipment was not delivered due to a car breakdown", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "A delay on PPL's side, such as the driver running out of time: nobody tried the recipient, and a later round delivers the parcel."},
+    {"code": "Undelivered.BadWeather", "wording": "The shipment was not delivered due to an adverse route situation beyond our control", "language": "en", "stage": "in_transit", "confirmedBy": "bundle", "note": "A delay on PPL's side, such as the driver running out of time: nobody tried the recipient, and a later round delivers the parcel."},
+    {"code": "LoadingForDelivery", "wording": "The shipment will be delivered today", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "The parcel is loaded for the day's round. The wording reads as a forecast, but the code is the loading scan."},
+    {"code": "LoadingForDelivery.TimeWindow", "wording": "The shipment will be delivered today", "language": "en", "stage": "out_for_delivery", "confirmedBy": "bundle", "note": "The portal adds the expected time window."},
+    {"code": "Delivery", "wording": "The shipment is being delivered to the recipient at the destination", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "A partner abroad is delivering the parcel."},
+    {"code": "NotDelivered.WasNotReached.Announced", "wording": "The shipment was not delivered due to failure to reach the recipient", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.WasNotReached.Unannounced", "wording": "The shipment was not delivered due to failure to reach the recipient", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.Holiday", "wording": "The shipment was not delivered due to failure to reach the recipient", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle", "note": "The portal words it as the recipient not being reached."},
+    {"code": "NotDelivered.Close", "wording": "The shipment was not delivered due to failure to reach the recipient", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle", "note": "The portal words it as the recipient not being reached."},
+    {"code": "NotDelivered.OtherDate", "wording": "We will deliver the shipment on another date", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle", "note": "Delivery moves to another day after an attempt."},
+    {"code": "NotDelivered.NewAddress", "wording": "We will deliver the shipment to a new address", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle", "note": "Delivery moves to a new address after an attempt."},
+    {"code": "NotDelivered.UnpreparedCash", "wording": "The shipment was not delivered due to unprepared cash", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.Documents", "wording": "The shipment was not delivered due to unprepared or incorrect documents", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.AgeLimit", "wording": "The shipment was not delivered due to the recipient’s age", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.IncompleteShipment", "wording": "The shipment was not delivered due to incompleteness", "language": "en", "stage": "exception", "confirmedBy": "bundle"},
+    {"code": "NotDelivered.IncompleteData", "wording": "The shipment was not delivered due to incomplete or incorrect delivery details", "language": "en", "stage": "exception", "confirmedBy": "bundle", "note": "The portal asks for the delivery details to be completed."},
+    {"code": "NotDelivered.Damage", "wording": "The shipment was not delivered due to damage", "language": "en", "stage": "exception", "confirmedBy": "bundle", "note": "The portal says the sender is told about the damage."},
+    {"code": "NotDelivered.BackToSender", "wording": "The recipient refused to accept the shipment due to the fact that the goods were not ordered", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "A refusal: the portal says the parcel goes back to the sender."},
+    {"code": "BackToSender.Refused", "wording": "The recipient refused to accept the shipment", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "A refusal: the portal says the parcel goes back to the sender."},
+    {"code": "BackToSender.Refused.NoReason", "wording": "The recipient refused to accept the shipment without giving a reason", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "A refusal: the portal says the parcel goes back to the sender."},
+    {"code": "BackToSender", "wording": "The shipment will be returned to the sender", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "The portal says the parcel is on its way back and cannot be delivered again."},
+    {"code": "BackToSender.NotPickedUp", "wording": "The shipment has not been collected by the recipient and will be returned to the sender", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "Nobody collected the parcel from the pickup point in time."},
+    {"code": "BackToSender.StorageTimeExceeded", "wording": "The shipment has not been collected by the recipient and will be returned to the sender", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "Nobody collected the parcel from the pickup point in time."},
+    {"code": "Delivered.BackToSender", "wording": "We have returned the shipment to the sender", "language": "en", "stage": "returned", "confirmedBy": "bundle", "note": "The sender has the parcel back."},
+    {"code": "Delivered.Parcelshop", "wording": "We have delivered the shipment to the pick-up point", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "firstSeen": "2026-10-11", "note": "A PPL ParcelShop or ParcelBox holds the parcel for the recipient; a later Delivered is the collection."},
+    {"code": "Delivered.ServicePoint", "wording": "We have delivered the shipment to the pick-up point abroad", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "bundle", "note": "A pickup point abroad holds the parcel."},
+    {"code": "Delivered", "wording": "We have delivered the shipment to the recipient", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-10-11"},
+    {"code": "Delivered.Uncomplete", "wording": "We have delivered the shipment to the recipient", "language": "en", "stage": "delivered", "confirmedBy": "bundle", "note": "Delivered incomplete; the portal words it as a delivery."},
+    {"code": "Delivered.Exception", "wording": "We have delivered the shipment to the recipient", "language": "en", "stage": "delivered", "confirmedBy": "bundle", "note": "Delivered with a remark; the portal words it as a delivery."},
+    {"code": "Delivered.Damaged", "wording": "We have delivered the shipment to the recipient", "language": "en", "stage": "delivered", "confirmedBy": "bundle", "note": "Delivered damaged; the portal words it as a delivery."},
+    {"code": "Cod.AdviceSent", "wording": "We have sent a payment order with a cash on delivery amount", "language": "en", "confirmedBy": "bundle", "note": "A cash-on-delivery payment step, not a movement: the parcel keeps the stage it had."},
+    {"code": "Cod.Completed", "wording": "The cash on delivery amount has been credited to the sender’s account", "language": "en", "confirmedBy": "bundle", "note": "A cash-on-delivery payment step, not a movement: the parcel keeps the stage it had."},
+    {"code": "Deleted", "wording": "The shipment has been deleted from the PPL system. Please contact the PPL customer service for more information", "language": "en", "stage": "exception", "confirmedBy": "bundle", "note": "Removed from PPL's system; the portal refers the recipient to customer service."}
+  ]
 }

package/dist/core/catalog/statusMaps.js

@@ -36,6 +36,7 @@ import { statusMap as oldDominion } from '../../carriers/old-dominion/status.js'
 import { statusMap as omgo } from '../../carriers/omgo/status.js';
 import { statusMap as orlenPaczka } from '../../carriers/orlen-paczka/status.js';
 import { statusMap as postlogistics } from '../../carriers/postlogistics/status.js';
+import { statusMap as ppl } from '../../carriers/ppl/status.js';
 import { statusMap as sagawa } from '../../carriers/sagawa/status.js';
 import { statusMap as sameday } from '../../carriers/sameday/status.js';
 import { statusMap as speedx } from '../../carriers/speedx/status.js';
@@ -54,8 +55,8 @@ export const STATUS_MAPS = {
     'acs-courier': acsCourier, aliexpress, 'an-post': anPost, 'box-now': boxNow, 'china-post': chinaPost, chronopost, 'correos-spain': correosSpain,
     'dhl-express': dhlExpress, dpd, 'dpd-de': dpdDe, 'dpd-fr': dpdFr, 'dpd-pl': dpdPl, econt, elta, emile, 'fan-courier': fanCourier, foxpost,
     'gofo-fr': gofoFr, 'gofo-it': gofoIt, 'j-and-t': jAndT, 'j-and-t-cargo': jntCargo, 'la-poste': laPoste, 'old-dominion': oldDominion, omgo,
-    'orlen-paczka': orlenPaczka, postlogistics, sagawa, sameday, speedx, speedy, sto, 'swiss-post': swissPost, 'thailand-post': thailandPost, tnt, ups,
-    yunexpress,
+    'orlen-paczka': orlenPaczka, postlogistics, ppl, sagawa, sameday, speedx, speedy, sto, 'swiss-post': swissPost, 'thailand-post': thailandPost, tnt,
+    ups, yunexpress,
 };
 /** The carrier the app files the universal providers' scans under. */
 const UNIVERSAL_CARRIER = 'unknown';

package/dist/data/catalog.json

@@ -7462,7 +7462,7 @@
         "timezone": "Europe/Prague",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "ppl"
         },
         "canaryUrl": "https://www.ppl.cz/vyhledat-zasilku",
         "trackingUrlTemplate": "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}",

package/dist/generated/catalog.d.ts

@@ -5011,7 +5011,7 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Europe/Prague";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "ppl";
         };
         readonly canaryUrl: "https://www.ppl.cz/vyhledat-zasilku";
         readonly trackingUrlTemplate: "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}";

package/dist/generated/catalog.js

@@ -7463,7 +7463,7 @@ export const CARRIER_CATALOG = {
         "timezone": "Europe/Prague",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "ppl"
         },
         "canaryUrl": "https://www.ppl.cz/vyhledat-zasilku",
         "trackingUrlTemplate": "https://www.ppl.cz/vyhledat-zasilku?shipmentId={trackingNumber}",

package/dist/generated/registry.js

@@ -96,6 +96,7 @@ 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';
 import { adapter as postnord } from '../carriers/postnord/adapter.js';
+import { adapter as ppl } from '../carriers/ppl/adapter.js';
 import { adapter as purolator } from '../carriers/purolator/adapter.js';
 import { adapter as relaisColis } from '../carriers/relais-colis/adapter.js';
 import { adapter as royalMail } from '../carriers/royal-mail/adapter.js';
@@ -227,6 +228,7 @@ export const REGISTRY = {
         "posti": posti,
         "postlogistics": postlogistics,
         "postnord": postnord,
+        "ppl": ppl,
         "purolator": purolator,
         "relais-colis": relaisColis,
         "royal-mail": royalMail,
@@ -413,7 +415,7 @@ export const REGISTRY = {
         "posti": "posti",
         "postlogistics": "postlogistics",
         "postnord": "postnord",
-        "ppl": "universal",
+        "ppl": "ppl",
         "ptt": "universal",
         "purolator": "purolator",
         "quickpac": "planzer",

package/dist/server/openapi.json

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

package/package.json

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