universal-parcel-scraper 0.1007.1-main.5444 → 0.1007.2-main.5446

package/dist/carriers/ctt/adapter.js

@@ -4,7 +4,7 @@ import { isValidS10TrackingNumber } from '../../core/detection/index.js';
 import { countryTimeZone, explicitOffsetTime, isoTime } from '../../core/time/index.js';
 import { clean, decodeText, escapeRegExp, fetchBounded, parseJsonBytes, } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
-import { agencyIntake, cttSiteZone, isCttExpressPlace, portugalZone } from './clock.js';
+import { agencyIntake, cttSiteZone, isCttExpressPlace, officeCountry, portugalZone } from './clock.js';
 import { classifyCttStatus } from './status.js';
 // Protocol provenance:
 // - Prior art (full session mechanics + vocabulary, verified step by step
@@ -86,6 +86,9 @@ function sessionFromSetCookie(response) {
 const DESTINATION_EVENT = /^(?:EM[D-I]|ED[A-H])$/;
 /** UPU events an origin post records: from posting to dispatch from its office of exchange. */
 const ORIGIN_EVENT = /^(?:EM[A-C]|EX[A-DX])$/;
+/** Stages a scan from the return's arrival back at the origin takes as part of the trip back. */
+const RETURN_TRIP = new Set(['accepted', 'in_transit', 'out_for_delivery', 'ready_for_pickup', 'delivered']);
+const RETURNED = { status: 'exception', stage: 'returned' };
 const WALL_CLOCK = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.\d{1,3})?(?:Z|\+00:?00)?$/i;
 /** A scan's wall clock read as UTC, only to compare it with another's. */
 function wallMillis(value) {
@@ -96,20 +99,22 @@ function wallMillis(value) {
  * A scan's clock. CTT's Z is no offset: the digits are the wall clock where
  * the scan happened (see clock.ts). That is the partner post's country
  * (`partner`) for its scans: the destination's on a parcel bound abroad, the
- * origin's on mail from abroad. A location naming an office or a site of
- * CTT's overrides it; Portugal's clock applies otherwise. In a country with
+ * origin's on mail from abroad. A location naming an office of exchange in
+ * Portugal or one of the parcel's `countries`, or a site of CTT's, overrides
+ * it: a parcel returned to its origin arrives at the origin's office. Portugal's
+ * clock applies otherwise. In a country with
  * several zones the scan keeps CTT's Z, the last guess: hours off, but the
  * reply keeps its instant. Only a wall clock sent with no Z stays a wall time
  * there. Any other offset is taken as sent.
  */
-function scanClock(value, location, partner, spanish) {
+function scanClock(value, location, partner, countries, spanish) {
     const raw = typeof value === 'string' ? value.trim() : '';
     const wall = WALL_CLOCK.exec(raw)?.[1];
     if (!wall) {
         const time = explicitOffsetTime(raw);
         return time ? { time: time.iso, timestamp: time.timestamp } : null;
     }
-    const zone = cttSiteZone(location, partner ? [partner] : []) ?? (spanish ? 'Europe/Madrid' : null)
+    const zone = cttSiteZone(location, countries) ?? (spanish ? 'Europe/Madrid' : null)
         ?? (partner ? countryTimeZone(partner) : portugalZone(location));
     const placed = zone ? isoTime(wall, zone) : null;
     if (placed)
@@ -161,7 +166,7 @@ export function parseCttTrackingResponse(payload, trackingNumber) {
         const partner = abroad && DESTINATION_EVENT.test(code) ? abroad : origin && ORIGIN_EVENT.test(code) ? origin : null;
         const at = wallMillis(rawEvent.DateTime);
         const spanish = !location && agencyIntake(at, agencyScans);
-        const clock = scanClock(rawEvent.DateTime, location, partner, spanish);
+        const clock = scanClock(rawEvent.DateTime, location, partner, [abroad, origin], spanish);
         if (!clock || !description)
             return;
         const identity = `${clock.time ?? clock.local_time}\u0000${description}\u0000${Number.isSafeInteger(stateId) ? stateId : ''}`;
@@ -187,9 +192,21 @@ export function parseCttTrackingResponse(payload, trackingNumber) {
             classified: classified ?? undefined,
             timestamp: clock.timestamp,
             index,
+            // Mail from abroad arriving at an office of exchange of the country it
+            // came from is a return back at its origin.
+            back: Boolean(origin && !abroad && DESTINATION_EVENT.test(code) && officeCountry(location) === origin),
         });
     });
     parsed.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    // From that arrival on, the scans are the trip back to the sender: a movement
+    // or a delivery among them is the return, not a delivery to the recipient.
+    const arrivedBack = parsed.map((item) => item.back).lastIndexOf(true);
+    for (const item of parsed.slice(0, arrivedBack + 1)) {
+        const trip = RETURN_TRIP.has(item.classified?.stage ?? '');
+        if (trip)
+            item.classified = RETURNED;
+        item.event = { ...item.event, ...(trip ? { stage: 'returned' } : {}), provider_leg: 'return' };
+    }
     const events = parsed.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
     const latest = parsed.find((item) => item.classified);
     if (!latest) {

package/dist/carriers/ctt/clock.d.ts

@@ -17,6 +17,8 @@ export declare function isCttExpressPlace(location: string): boolean;
  * read as UTC, only to compare them. It is on Madrid's clock, as the agency's scan is.
  */
 export declare function agencyIntake(at: number, agencyScans: readonly number[]): boolean;
+/** The country of the office of exchange leading a location, if one does. */
+export declare function officeCountry(location: string): string | null;
 /**
  * The clock a CTT scan's location itself names: the country of the office of
  * exchange leading it, when that is Portugal or one of `countries` (the

package/dist/carriers/ctt/clock.js

@@ -88,6 +88,10 @@ const AGENCY_INTAKE_MS = 60_000;
 export function agencyIntake(at, agencyScans) {
     return agencyScans.some((agency) => agency - at >= 0 && agency - at <= AGENCY_INTAKE_MS);
 }
+/** The country of the office of exchange leading a location, if one does. */
+export function officeCountry(location) {
+    return OFFICE.exec(location)?.[1] ?? null;
+}
 /**
  * The clock a CTT scan's location itself names: the country of the office of
  * exchange leading it, when that is Portugal or one of `countries` (the
@@ -97,7 +101,7 @@ export function agencyIntake(at, agencyScans) {
  * the same clocks.
  */
 export function cttSiteZone(location, countries) {
-    const office = OFFICE.exec(location)?.[1];
+    const office = officeCountry(location);
     if (office === 'PT' || (office && countries.includes(office))) {
         return office === 'PT' ? portugalZone(location) : countryTimeZone(office);
     }

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.1007.1-main.5444"
+    "version": "0.1007.2-main.5446"
   },
   "paths": {
     "/health": {

package/package.json

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