universal-parcel-scraper 0.53.0-main.667 → 0.53.0-main.670

package/README.md

@@ -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 2,993 such statuses, each filed under one stage.
+The carrier folders record 2,998 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/dist/carriers/dpd-de/service.js

@@ -14,8 +14,8 @@ const MAX_BYTES = 2_000_000;
 /** Opening a session has taken up to 75 seconds. */
 const SESSION_OPEN_MS = 120_000;
 /**
- * The service accepts a session for at least four hours, an idle one too. From this age the next
- * one opens beside it, and replaces it once open.
+ * The service accepts a session for at least eight hours, one left idle for four too. From this
+ * age the next one opens beside it, and replaces it once open.
  */
 const SESSION_RENEW_MS = 3 * 3_600_000;
 /** A kept session that failed to open is tried again after this long. */

package/dist/carriers/ecoscooting/parser.js

@@ -81,10 +81,11 @@ export function parseEcoscooting(payload, rawNumber) {
 }
 // A shop's name and address, once a scan places the parcel there. It stays
 // after collection so the parcel still says where it was collected, but a
-// delivery by the courier, at the door, has none. The pickup PIN, the shop's
-// phone and the station id are never read.
+// delivery by the courier, at the door, has none, and neither has a parcel on
+// its way back to the sender, which no longer waits there. The pickup PIN, the
+// shop's phone and the station id are never read.
 function pickupPoint(station, events, stage) {
-    if (!isRecord(station) || !events.some(event => PICKUP_POINT_CODES.has(String(event.provider_code))))
+    if (!isRecord(station) || stage === 'returned' || !events.some(event => PICKUP_POINT_CODES.has(String(event.provider_code))))
         return {};
     if (stage === 'delivered' && !COLLECTION_CODES.has(String(events[0]?.provider_code)))
         return {};

package/dist/carriers/packeta/adapter.js

@@ -2,7 +2,7 @@ import { lookupBudget } from '../../core/adapter/index.js';
 import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { lastMovement } from '../../core/result/pickup.js';
 import { zonedTime } from '../../core/time/index.js';
-import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf } from '../../core/transport/index.js';
+import { clean, cleanScalar, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyPacketaStatus, packetaEventStage } from './status.js';
 // Protocol provenance:
@@ -15,10 +15,11 @@ import { classifyPacketaStatus, packetaEventStage } from './status.js';
 //   Expired 2023-era reported Z codes return the same 404 (unknown and expired
 //   are intentionally indistinguishable to anonymous callers).
 // - Shape reference: the prior-art payload samples (confirmed live 2026-08-19
-//   against real delivered parcels; values fictionalized there). Only
-//   packetStatusId "3" (delivered) is live-confirmed; the other codes are
-//   reconstructed — an unmapped code is schema drift, never a guess. The maps
-//   live in status.ts.
+//   against real delivered parcels; values fictionalized there). The
+//   packetStatusId names come from the public tracking page's own script;
+//   only "3" (delivered), "5" and "21" (returns) are live-confirmed, the other
+//   codes are reconstructed — an unmapped code is schema drift, never a guess.
+//   The maps live in status.ts.
 const TRACKING_ENDPOINT = 'https://tracking.packeta.com/api/getPacketById';
 const TRACKING_LOCALE = 'en';
 const DEFAULT_TIMEOUT_MS = 15_000;
@@ -100,12 +101,15 @@ export function parsePacketaTrackingResponse(payload, trackingNumber) {
     const events = parsed.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
     // Sender (merchant) and branchAddress (Z-BOX/partner shop) carry no
     // recipient PII and are the only pickup signal — Packeta exposes no ETA.
-    // For a parcel a courier brings to the door, branchAddress names a
-    // home-delivery branch, so a delivered parcel keeps it only when its last
-    // movement made it ready for pickup.
+    // For a parcel a courier brings to the door, courierId is "1" and
+    // branchAddress names a home-delivery branch, which Packeta's own page does
+    // not link to. A returned parcel's branch is a depot or the point it no
+    // longer waits at, and a delivered one keeps its branch only when its last
+    // movement made it ready for pickup there.
     const sender = clean(item.sender, 200) || null;
-    const pickupPoint = classified?.stage === 'delivered' && lastMovement(events) !== 'ready_for_pickup'
-        ? null : clean(item.branchAddress, 300) || null;
+    const atPoint = cleanScalar(item.courierId, 8) !== '1' && classified?.stage !== 'returned'
+        && (classified?.stage !== 'delivered' || lastMovement(events) === 'ready_for_pickup');
+    const pickupPoint = atPoint ? clean(item.branchAddress, 300) || null : null;
     const deliveredAt = classified?.status === 'delivered' ? events[0]?.time ?? null : null;
     if (!classified) {
         return {

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

@@ -11,10 +11,12 @@
  *   where the final stage came from.
  *
  * Provenance: derived from the prior-art client
- * https://github.com/ha-parcel-integrations/ha-packeta (MIT). Only
- * `packetStatusId` "3" (delivered) is live-confirmed there; the other ids are
- * reconstructed. The event sentences were confirmed live on 2026-08-19 against
- * real delivered parcels (values fictionalized in that project's fixtures).
+ * https://github.com/ha-parcel-integrations/ha-packeta (MIT), and from the id
+ * names the public tracking page's own script declares (read 2026-10-09).
+ * `packetStatusId` "3" (delivered), "5" (returned to sender) and "21" are
+ * live-confirmed; the other ids are reconstructed. The event sentences were
+ * confirmed live on 2026-08-19 against real delivered parcels (values
+ * fictionalized in that project's fixtures); the return's sentence on 2026-10-09.
  */
 import type { ClassifiedStatus, Stage } from '../../core/status/index.js';
 /** The stage and status for a `packetStatusId`, or undefined when unmapped. */

package/dist/carriers/packeta/status.js

@@ -1,3 +1,4 @@
+const RETURNED = { status: 'exception', stage: 'returned' };
 const PACKET_STATUS = {
     // TO_BE_PROCESSED
     '997': { status: 'pending', stage: 'registered' },
@@ -7,11 +8,20 @@ const PACKET_STATUS = {
     '31': { status: 'in_transit', stage: 'in_transit' },
     // READY_FOR_PICKUP
     '2': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    // READY_LAST_DAY: the last day it waits at the point
+    '996': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
     // ISSUED_AND_ACCOUNTED (live-confirmed delivered wording:
     // "The package has been delivered")
     '3': { status: 'delivered', stage: 'delivered' },
-    // LOST_OR_UNKNOWN
-    '21': { status: 'exception', stage: 'failed_attempt' },
+    // RETURNED_AND_ACCOUNTED (live wording "Returned to sender")
+    '5': RETURNED,
+    // RETURN
+    '20': RETURNED,
+    // TO_BE_RETURNED
+    '998': RETURNED,
+    // Named LOST_OR_UNKNOWN in the page's script, but worded "Return (on the way
+    // back)" live.
+    '21': RETURNED,
 };
 const EVENT_TEXT_STAGES = [
     ['aware of your parcel and are waiting for the sender', 'registered'],
@@ -24,6 +34,7 @@ const EVENT_TEXT_STAGES = [
     ['ready for pickup', 'ready_for_pickup'],
     ['the parcel is with you', 'delivered'],
     ['investigating the status of the parcel', 'failed_attempt'],
+    ['returned the parcel back to the sender', 'returned'],
 ];
 /** The stage and status for a `packetStatusId`, or undefined when unmapped. */
 export function classifyPacketaStatus(code) {

package/dist/carriers/packeta/statuses.json

@@ -5,8 +5,12 @@
     { "code": "1", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "WAITING_FOR_DELIVERY (in warehouse); reconstructed." },
     { "code": "31", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "ON_THE_WAY; reconstructed." },
     { "code": "2", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "READY_FOR_PICKUP; reconstructed." },
+    { "code": "996", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "bundle", "firstSeen": "2026-10-09", "note": "READY_LAST_DAY, named in the tracking page's script; not observed." },
     { "code": "3", "wording": "The package has been delivered", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "ISSUED_AND_ACCOUNTED; the only packetStatusId confirmed against real delivered parcels." },
-    { "code": "21", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "LOST_OR_UNKNOWN; reconstructed." },
+    { "code": "5", "wording": "Returned to sender", "language": "en", "stage": "returned", "confirmedBy": "live", "firstSeen": "2026-10-09", "note": "RETURNED_AND_ACCOUNTED, named in the tracking page's script." },
+    { "code": "20", "language": "en", "stage": "returned", "confirmedBy": "bundle", "firstSeen": "2026-10-09", "note": "RETURN, named in the tracking page's script; not observed." },
+    { "code": "998", "language": "en", "stage": "returned", "confirmedBy": "bundle", "firstSeen": "2026-10-09", "note": "TO_BE_RETURNED, named in the tracking page's script; not observed." },
+    { "code": "21", "wording": "Return (on the way back)", "language": "en", "stage": "returned", "confirmedBy": "live", "firstSeen": "2026-10-09", "note": "Named LOST_OR_UNKNOWN in the tracking page's script, but worded as a return live." },
     { "wording": "We are aware of your parcel and are waiting for the sender…", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
     { "wording": "…assigned a tracking number…", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
     { "wording": "…successfully received the parcel for transport…", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
@@ -16,6 +20,7 @@
     { "wording": "…on its way to you…", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
     { "wording": "The parcel is ready for pickup…", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
     { "wording": "The parcel is with you…", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
-    { "wording": "…investigating the status of the parcel…", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." }
+    { "wording": "…investigating the status of the parcel…", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "We have returned the parcel back to the sender.", "language": "en", "stage": "returned", "confirmedBy": "live", "firstSeen": "2026-10-09", "note": "Event sentence; substring match." }
   ]
 }

package/package.json

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