universal-parcel-scraper 0.3.2-main.314 → 0.3.4-main.317

package/README.md

@@ -15,7 +15,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 <!-- GENERATED:summary -->
 **3,500+ carriers** through **85 dedicated adapters** and **5 universal fallbacks**
 
-<sub>105 carriers in the catalog · 58 countries represented</sub>
+<sub>105 catalog entries · 58 countries represented</sub>
 <!-- /GENERATED:summary -->
 
 [Try it](#try-it) · [Ways to run it](#ways-to-run-it) · [Benchmark](#benchmark) · [Carriers](carriers/) · [Add a carrier](CONTRIBUTING.md)
@@ -33,9 +33,9 @@ its own as a command, a Node library or an HTTP server.
 ## Benchmark
 
 <!-- GENERATED:coverage -->
-Benchmarked against 100 popular carriers, it returns tracking history for **70**. The best single aggregator returns 50.
+In a curated benchmark of 100 carriers, dedicated adapters return tracking history for **62**, rising to **75** with all fallbacks enabled. The best single aggregator returns 52.
 
-<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 70, This project, dedicated adapters alone 51, ParcelsApp 50, Postal Ninja 41, 17TRACK 40, Ship24 38, UPU 11." width="760">
+<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 75, This project, dedicated adapters alone 62, ParcelsApp 52, Postal Ninja 43, 17TRACK 40, Ship24 41, UPU 12." width="760">
 <!-- /GENERATED:coverage -->
 
 [Method and results per carrier](providers/COVERAGE.md)
@@ -149,7 +149,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 1,672 such statuses, each filed under one stage.
+The carrier folders record 1,673 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/coverage-summary.json

@@ -4,14 +4,14 @@
   "countries": 58,
   "referenceCarriers": 100,
   "comparison": {
-    "combined": 70,
-    "direct": 51,
+    "combined": 75,
+    "direct": 62,
     "providers": {
-      "ParcelsApp": 50,
-      "Postal Ninja": 41,
+      "ParcelsApp": 52,
+      "Postal Ninja": 43,
       "17TRACK": 40,
-      "Ship24": 38,
-      "UPU": 11
+      "Ship24": 41,
+      "UPU": 12
     }
   }
 }

package/dist/browser/scraper.js

@@ -8111,20 +8111,36 @@ var fs = { carriers: [
 	{
 		carrier: "bpost",
 		direct: "Yes",
-		sample: "No history; alternate ✓ 11",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: "postcode_prompt",
-			"17TRACK": "no_history",
-			"Postal Ninja": "no_history",
-			UPU: "n/a"
-		} }, {
-			note: "An S10 item through Landmark Global",
-			results: {
-				ParcelsApp: 20,
-				"17TRACK": 14
+		sample: "✓ 11",
+		references: [
+			{
+				note: "A domestic parcel",
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "postcode_prompt",
+					"17TRACK": "no_history",
+					"Postal Ninja": "no_history",
+					UPU: "n/a"
+				}
+			},
+			{
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "postcode_prompt",
+					"17TRACK": "no_history",
+					"Postal Ninja": "no_history",
+					UPU: "n/a"
+				},
+				note: "Another comparison reference"
+			},
+			{
+				note: "An S10 item through Landmark Global",
+				results: {
+					ParcelsApp: 20,
+					"17TRACK": 14
+				}
 			}
-		}]
+		]
 	},
 	{
 		carrier: "austrian-post",
@@ -8171,25 +8187,41 @@ var fs = { carriers: [
 	{
 		carrier: "aramex",
 		direct: "Yes",
-		sample: "No history; alternate ✓ 26",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: "no_history",
-			"17TRACK": "no_history",
-			"Postal Ninja": {
-				rows: 16,
-				partial: "undated rows"
+		sample: "✓ 16",
+		references: [
+			{
+				note: "A domestic shipment",
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "no_history",
+					"17TRACK": "no_history",
+					"Postal Ninja": 16,
+					UPU: "n/a"
+				}
 			},
-			UPU: "n/a"
-		} }, {
-			note: "An international shipment",
-			results: {
-				Ship24: 26,
-				ParcelsApp: "no_history",
-				"17TRACK": 26,
-				"Postal Ninja": 26
+			{
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "no_history",
+					"17TRACK": "no_history",
+					"Postal Ninja": {
+						rows: 16,
+						partial: "undated rows"
+					},
+					UPU: "n/a"
+				},
+				note: "Another comparison reference"
+			},
+			{
+				note: "An international shipment",
+				results: {
+					Ship24: 26,
+					ParcelsApp: "no_history",
+					"17TRACK": 26,
+					"Postal Ninja": 26
+				}
 			}
-		}]
+		]
 	},
 	{
 		carrier: "yunexpress",
@@ -8317,14 +8349,26 @@ var fs = { carriers: [
 	{
 		carrier: "correios-br",
 		direct: "Yes (local OCR)",
-		sample: "No history; alternate ✓ 14",
-		references: [{ results: {
-			Ship24: 8,
-			ParcelsApp: "no_history",
-			"17TRACK": 8,
-			"Postal Ninja": 8,
-			UPU: "no_history"
-		} }]
+		sample: "✓ 8",
+		references: [{
+			note: "A Brazilian postal item",
+			results: {
+				Ship24: 8,
+				ParcelsApp: "no_history",
+				"17TRACK": 8,
+				"Postal Ninja": "error",
+				UPU: "no_history"
+			}
+		}, {
+			results: {
+				Ship24: 8,
+				ParcelsApp: "no_history",
+				"17TRACK": 8,
+				"Postal Ninja": 8,
+				UPU: "no_history"
+			},
+			note: "Another comparison reference"
+		}]
 	},
 	{
 		carrier: "singapore-post",
@@ -8359,23 +8403,39 @@ var fs = { carriers: [
 	{
 		carrier: "korea-post",
 		direct: "Yes (international)",
-		sample: "Domestic unsupported; alternate ✓ 20",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: "no_history",
-			"17TRACK": "no_history",
-			"Postal Ninja": "no_history",
-			UPU: "n/a"
-		} }, {
-			note: "An EMS item",
-			results: {
-				Ship24: "history",
-				ParcelsApp: "history",
-				"17TRACK": "history",
-				"Postal Ninja": "no_history",
-				UPU: "history"
+		sample: "✓ 20",
+		references: [
+			{
+				note: "An EMS item",
+				results: {
+					Ship24: 36,
+					ParcelsApp: 41,
+					"17TRACK": 28,
+					"Postal Ninja": 27,
+					UPU: 1
+				}
+			},
+			{
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "no_history",
+					"17TRACK": "no_history",
+					"Postal Ninja": "no_history",
+					UPU: "n/a"
+				},
+				note: "Another comparison reference"
+			},
+			{
+				note: "An EMS item",
+				results: {
+					Ship24: "history",
+					ParcelsApp: "history",
+					"17TRACK": "history",
+					"Postal Ninja": "no_history",
+					UPU: "history"
+				}
 			}
-		}]
+		]
 	},
 	{
 		carrier: "planzer",
@@ -8461,14 +8521,26 @@ var fs = { carriers: [
 	{
 		carrier: "delhivery",
 		direct: "Yes",
-		sample: "No history; alternate summary + 1 undated scan",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: "no_history",
-			"17TRACK": "no_history",
-			"Postal Ninja": "no_history",
-			UPU: "n/a"
-		} }]
+		sample: "✓ 2, partial (one undated scan and a status snapshot)",
+		references: [{
+			note: "A domestic parcel",
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: "no_history",
+				"17TRACK": "no_history",
+				"Postal Ninja": "no_history",
+				UPU: "n/a"
+			}
+		}, {
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: "no_history",
+				"17TRACK": "no_history",
+				"Postal Ninja": "no_history",
+				UPU: "n/a"
+			},
+			note: "Another comparison reference"
+		}]
 	},
 	{
 		carrier: "blue-dart",
@@ -8485,14 +8557,26 @@ var fs = { carriers: [
 	{
 		carrier: "dtdc",
 		direct: "Yes",
-		sample: "No history; alternate ✓ 9",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: 35,
-			"17TRACK": "no_history",
-			"Postal Ninja": "refused",
-			UPU: "n/a"
-		} }]
+		sample: "✓ 9",
+		references: [{
+			note: "A domestic parcel",
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: 37,
+				"17TRACK": "no_history",
+				"Postal Ninja": "no_history",
+				UPU: "n/a"
+			}
+		}, {
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: 35,
+				"17TRACK": "no_history",
+				"Postal Ninja": "refused",
+				UPU: "n/a"
+			},
+			note: "Another comparison reference"
+		}]
 	},
 	{
 		carrier: "ninja-van",
@@ -8509,8 +8593,17 @@ var fs = { carriers: [
 	{
 		carrier: "packeta",
 		direct: "Yes",
-		sample: "No history",
+		sample: "✓ 6",
 		references: [{
+			note: "A parcel handed to a delivery partner",
+			results: {
+				Ship24: 11,
+				ParcelsApp: "no_history",
+				"17TRACK": "no_history",
+				"Postal Ninja": 12,
+				UPU: "n/a"
+			}
+		}, {
 			stale: !0,
 			results: {
 				Ship24: "no_history",
@@ -8518,7 +8611,8 @@ var fs = { carriers: [
 				"17TRACK": "no_history",
 				"Postal Ninja": "no_history",
 				UPU: "n/a"
-			}
+			},
+			note: "Another comparison reference"
 		}]
 	},
 	{
@@ -8542,14 +8636,26 @@ var fs = { carriers: [
 	{
 		carrier: "bring-posten",
 		direct: "Yes",
-		sample: "Not tested; alternate ✓ 3",
-		references: [{ results: {
-			Ship24: 12,
-			ParcelsApp: 15,
-			"17TRACK": 19,
-			"Postal Ninja": 16,
-			UPU: 3
-		} }]
+		sample: "✓ 12",
+		references: [{
+			note: "A Norwegian postal item",
+			results: {
+				Ship24: 12,
+				ParcelsApp: 15,
+				"17TRACK": 19,
+				"Postal Ninja": 16,
+				UPU: 3
+			}
+		}, {
+			results: {
+				Ship24: 12,
+				ParcelsApp: 15,
+				"17TRACK": 19,
+				"Postal Ninja": 16,
+				UPU: 3
+			},
+			note: "Another comparison reference"
+		}]
 	},
 	{
 		carrier: "posti",
@@ -8602,14 +8708,26 @@ var fs = { carriers: [
 	{
 		carrier: "brt",
 		direct: "Yes",
-		sample: "Not tested; alternate ✓ 7",
-		references: [{ results: {
-			Ship24: "no_history",
-			ParcelsApp: 23,
-			"17TRACK": "no_history",
-			"Postal Ninja": 5,
-			UPU: "n/a"
-		} }]
+		sample: "✓ 9",
+		references: [{
+			note: "An international parcel",
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: 23,
+				"17TRACK": "no_history",
+				"Postal Ninja": 5,
+				UPU: "n/a"
+			}
+		}, {
+			results: {
+				Ship24: "no_history",
+				ParcelsApp: 23,
+				"17TRACK": "no_history",
+				"Postal Ninja": 5,
+				UPU: "n/a"
+			},
+			note: "Another comparison reference"
+		}]
 	},
 	{
 		carrier: "seur",
@@ -8638,38 +8756,64 @@ var fs = { carriers: [
 	{
 		carrier: "mrw",
 		direct: "Yes",
-		sample: "Summary only; alternate ✓ 14",
+		sample: "✓ 14",
+		references: [
+			{
+				note: "A delivered parcel",
+				results: {
+					Ship24: 14,
+					ParcelsApp: 14,
+					"17TRACK": "no_history",
+					"Postal Ninja": 14,
+					UPU: "n/a"
+				}
+			},
+			{
+				stale: !0,
+				results: {
+					Ship24: "no_history",
+					ParcelsApp: "no_history",
+					"17TRACK": 1,
+					"Postal Ninja": "no_history",
+					UPU: "n/a"
+				},
+				note: "Another comparison reference"
+			},
+			{
+				note: "A September parcel",
+				results: {
+					Ship24: 14,
+					ParcelsApp: 14,
+					"17TRACK": "no_history",
+					"Postal Ninja": 14
+				}
+			}
+		]
+	},
+	{
+		carrier: "nacex",
+		direct: "Yes",
+		sample: "✓ 13",
 		references: [{
-			stale: !0,
+			note: "An agency/shipment reference",
 			results: {
-				Ship24: "no_history",
-				ParcelsApp: "no_history",
-				"17TRACK": 1,
-				"Postal Ninja": "no_history",
+				Ship24: "refused",
+				ParcelsApp: "refused",
+				"17TRACK": "refused",
+				"Postal Ninja": "refused",
 				UPU: "n/a"
 			}
 		}, {
-			note: "A September parcel",
 			results: {
-				Ship24: 14,
-				ParcelsApp: 14,
-				"17TRACK": "no_history",
-				"Postal Ninja": 14
-			}
+				Ship24: "error",
+				ParcelsApp: "error",
+				"17TRACK": "error",
+				"Postal Ninja": "error",
+				UPU: "n/a"
+			},
+			note: "Another comparison reference"
 		}]
 	},
-	{
-		carrier: "nacex",
-		direct: "Yes",
-		sample: "Not tested; alternate ✓ 14",
-		references: [{ results: {
-			Ship24: "error",
-			ParcelsApp: "error",
-			"17TRACK": "error",
-			"Postal Ninja": "error",
-			UPU: "n/a"
-		} }]
-	},
 	{
 		carrier: "colis-prive",
 		direct: "Yes (postcode)",

package/dist/carriers/delhivery/parser.js

@@ -22,7 +22,8 @@ export function parseDelhivery(payload, number) {
         throw new SchemaError('Delhivery');
     if (!payload.data.length && payload.message === 'invalid AWB or very old package')
         throw new NotFoundError('Delhivery');
-    const matches = payload.data.filter(isRecord).filter(item => clean(item.awb, 64) === requested);
+    const matches = payload.data.filter(isRecord).filter(item => (typeof item.awb === 'string' ? item.awb.trim()
+        : typeof item.awb === 'number' && Number.isSafeInteger(item.awb) ? String(item.awb) : '') === requested);
     if (matches.length !== 1)
         throw new SchemaError('Delhivery', 'Delhivery did not return one matching shipment');
     const item = matches[0];
@@ -31,7 +32,14 @@ export function parseDelhivery(payload, number) {
     const description = clean(item.status.status, 200);
     if (!description)
         throw new IndeterminateError('Delhivery', 'Delhivery returned no current status');
-    const mapped = classifyDelhiveryStatus(description);
+    const returning = item.status.statusType === 'RT' || item.currentFlow === 'Returned' || item.currentFlow === 'Reverse';
+    // RETURNED names a flow, including parcels still travelling to the sender.
+    // The separate shipment status establishes movement or completed delivery.
+    const snapshotDescription = returning && description.toUpperCase() === 'RETURNED'
+        ? clean(item.hqStatus, 200) : description;
+    const current = classifyDelhiveryStatus(snapshotDescription);
+    const mapped = returning && current?.stage === 'delivered'
+        ? classifyDelhiveryStatus('RTO DELIVERED') : current;
     const updated = scanTime(item.status.statusDateTime);
     const currentTimeText = clean(item.status.statusDateTime, 64);
     const events = [];
@@ -56,21 +64,25 @@ export function parseDelhivery(payload, number) {
             const time = scanTime(scan.scanDateTime);
             const timeText = clean(scan.scanDateTime, 64);
             const location = clean(scan.cityLocation, 160);
-            const key = `${time?.timestamp ?? timeText}\u0000${label}\u0000${location}`;
+            const returnScan = scan.scanType === 'RT' || item.currentFlow === 'Reverse';
+            const key = `${time?.timestamp ?? timeText}\u0000${label}\u0000${location}\u0000${returnScan ? 'return' : ''}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const classified = classifyDelhiveryStatus(label);
+            const scanStatus = classifyDelhiveryStatus(label);
+            const classified = returnScan && scanStatus?.stage === 'delivered'
+                ? classifyDelhiveryStatus('RTO DELIVERED') : scanStatus;
             events.push({ description: label, ...(time ? { time: time.iso } : timeText ? { provider_time_text: timeText } : {}), ...(location ? { location } : {}),
-                ...(classified ? { stage: classified.stage } : {}) });
+                ...(classified ? { stage: classified.stage } : {}), ...(returnScan ? { provider_leg: 'return' } : {}) });
         }
     }
     // Repeated scan labels cannot bind a summary timestamp to a particular
     // historical location. Keep the dated status snapshot separate.
-    if (!updated || !events.some(event => event.time && Date.parse(event.time) === updated.timestamp
-        && event.description?.toUpperCase() === description.toUpperCase())) {
-        events.unshift({ description, ...(updated ? { time: updated.iso } : currentTimeText ? { provider_time_text: currentTimeText } : {}),
-            ...(mapped ? { stage: mapped.stage } : {}), summary_snapshot: true });
+    if (snapshotDescription && (!updated || !events.some(event => event.time && Date.parse(event.time) === updated.timestamp
+        && event.description?.toUpperCase() === snapshotDescription.toUpperCase() && event.stage === mapped?.stage
+        && (!returning || event.provider_leg === 'return')))) {
+        events.unshift({ description: snapshotDescription, ...(updated ? { time: updated.iso } : currentTimeText ? { provider_time_text: currentTimeText } : {}),
+            ...(mapped ? { stage: mapped.stage } : {}), ...(returning ? { provider_leg: 'return' } : {}), summary_snapshot: true });
     }
     const dated = events.filter(event => event.time).sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
     const undated = events.filter(event => !event.time);

package/dist/carriers/delhivery/status.js

@@ -2,9 +2,11 @@ const statuses = {
     DELIVERED: { status: 'delivered', stage: 'delivered' },
     'OUT FOR DELIVERY': { status: 'out_for_delivery', stage: 'out_for_delivery' },
     'IN TRANSIT': { status: 'in_transit', stage: 'in_transit' },
+    'IN TRANSIT FOR RETURN': { status: 'in_transit', stage: 'in_transit' },
     'PICKED UP': { status: 'in_transit', stage: 'accepted' },
     MANIFESTED: { status: 'pending', stage: 'registered' },
     'RTO DELIVERED': { status: 'exception', stage: 'returned' },
+    DELIVERED_SELLER: { status: 'exception', stage: 'returned' },
 };
 export function classifyDelhiveryStatus(value) {
     return statuses[value.toUpperCase()];

package/dist/carriers/delhivery/statuses.json

@@ -6,6 +6,12 @@
       "language": "en",
       "stage": "delivered",
       "confirmedBy": "live"
+    },
+    {
+      "wording": "In Transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
     }
   ]
 }

package/dist/carriers/packeta/adapter.js

@@ -1,5 +1,5 @@
 import { lookupBudget } from '../../core/adapter/index.js';
-import { InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { zonedTime } from '../../core/time/index.js';
 import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
@@ -52,18 +52,22 @@ export function parsePacketaTrackingResponse(payload, trackingNumber) {
     if (!isRecord(payload))
         throw new SchemaError('Packeta', 'Packeta returned an invalid tracking response');
     const item = payload.item;
-    // A 200 carrying an error instead of an item is Packeta's second unknown-code
-    // signal (mirrors the HTTP 404 contract); it is a domain outcome, not a crash.
+    // Only the named notFound error establishes absence; other API errors say
+    // nothing about the requested parcel.
     if (!isRecord(item)) {
-        if (typeof payload.error === 'string')
+        if (payload.error === 'notFound')
             throw new NotFoundError('Packeta');
+        if (typeof payload.error === 'string')
+            throw new IndeterminateError('Packeta', 'Packeta returned a tracking error');
         throw new SchemaError('Packeta', 'Packeta returned an invalid tracking response');
     }
-    const returned = clean(item.barcode, 64).toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    const returned = typeof item.barcode === 'string'
+        ? item.barcode.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '') : '';
     if (!returned)
         throw new SchemaError('Packeta', 'Packeta did not return a shipment identifier');
-    if (returned !== requested)
+    if (returned !== requested && returned !== requested.slice(1)) {
         throw new SchemaError('Packeta', 'Packeta returned a different shipment');
+    }
     const code = clean(item.packetStatusId, 16);
     const classified = classifyPacketaStatus(code);
     const rawDetails = item.trackingDetails;
@@ -157,8 +161,18 @@ export class PacketaTracker {
             allowHttpError: true,
             fetcher: this.fetcher,
         });
-        if (response.status === 404)
-            throw new NotFoundError('Packeta');
+        if (response.status === 404) {
+            let payload;
+            try {
+                payload = parseJsonBytes(bytes, 'Packeta tracking');
+            }
+            catch {
+                throw new UpstreamHttpError('Packeta tracking', response.status);
+            }
+            if (isRecord(payload) && payload.error === 'notFound')
+                throw new NotFoundError('Packeta');
+            throw new UpstreamHttpError('Packeta tracking', response.status);
+        }
         if (!response.ok)
             throw new UpstreamHttpError('Packeta tracking', response.status);
         return parsePacketaTrackingResponse(parseJsonBytes(bytes, 'Packeta tracking'), trackingNumber);

package/dist/providers/coverage.json

@@ -531,9 +531,10 @@
     {
       "carrier": "bpost",
       "direct": "Yes",
-      "sample": "No history; alternate ✓ 11",
+      "sample": "✓ 11",
       "references": [
         {
+          "note": "A domestic parcel",
           "results": {
             "Ship24": "no_history",
             "ParcelsApp": "postcode_prompt",
@@ -542,6 +543,16 @@
             "UPU": "n/a"
           }
         },
+        {
+          "results": {
+            "Ship24": "no_history",
+            "ParcelsApp": "postcode_prompt",
+            "17TRACK": "no_history",
+            "Postal Ninja": "no_history",
+            "UPU": "n/a"
+          },
+          "note": "Another comparison reference"
+        },
         {
           "note": "An S10 item through Landmark Global",
           "results": {
@@ -608,8 +619,18 @@
     {
       "carrier": "aramex",
       "direct": "Yes",
-      "sample": "No history; alternate ✓ 26",
+      "sample": "✓ 16",
       "references": [
+        {
+          "note": "A domestic shipment",
+          "results": {
+            "Ship24": "no_history",
+            "ParcelsApp": "no_history",
+            "17TRACK": "no_history",
+            "Postal Ninja": 16,
+            "UPU": "n/a"
+          }
+        },
         {
           "results": {
             "Ship24": "no_history",
@@ -620,7 +641,8 @@
               "partial": "undated rows"
             },
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         },
         {
           "note": "An international shipment",
@@ -799,16 +821,27 @@
     {
       "carrier": "correios-br",
       "direct": "Yes (local OCR)",
-      "sample": "No history; alternate ✓ 14",
+      "sample": "✓ 8",
       "references": [
         {
+          "note": "A Brazilian postal item",
           "results": {
             "Ship24": 8,
             "ParcelsApp": "no_history",
             "17TRACK": 8,
-            "Postal Ninja": 8,
+            "Postal Ninja": "error",
             "UPU": "no_history"
           }
+        },
+        {
+          "results": {
+            "Ship24": 8,
+            "ParcelsApp": "no_history",
+            "17TRACK": 8,
+            "Postal Ninja": 8,
+            "UPU": "no_history"
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -853,8 +886,18 @@
     {
       "carrier": "korea-post",
       "direct": "Yes (international)",
-      "sample": "Domestic unsupported; alternate ✓ 20",
+      "sample": "✓ 20",
       "references": [
+        {
+          "note": "An EMS item",
+          "results": {
+            "Ship24": 36,
+            "ParcelsApp": 41,
+            "17TRACK": 28,
+            "Postal Ninja": 27,
+            "UPU": 1
+          }
+        },
         {
           "results": {
             "Ship24": "no_history",
@@ -862,7 +905,8 @@
             "17TRACK": "no_history",
             "Postal Ninja": "no_history",
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         },
         {
           "note": "An EMS item",
@@ -982,9 +1026,10 @@
     {
       "carrier": "delhivery",
       "direct": "Yes",
-      "sample": "No history; alternate summary + 1 undated scan",
+      "sample": "✓ 2, partial (one undated scan and a status snapshot)",
       "references": [
         {
+          "note": "A domestic parcel",
           "results": {
             "Ship24": "no_history",
             "ParcelsApp": "no_history",
@@ -992,6 +1037,16 @@
             "Postal Ninja": "no_history",
             "UPU": "n/a"
           }
+        },
+        {
+          "results": {
+            "Ship24": "no_history",
+            "ParcelsApp": "no_history",
+            "17TRACK": "no_history",
+            "Postal Ninja": "no_history",
+            "UPU": "n/a"
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -1014,8 +1069,18 @@
     {
       "carrier": "dtdc",
       "direct": "Yes",
-      "sample": "No history; alternate ✓ 9",
+      "sample": "✓ 9",
       "references": [
+        {
+          "note": "A domestic parcel",
+          "results": {
+            "Ship24": "no_history",
+            "ParcelsApp": 37,
+            "17TRACK": "no_history",
+            "Postal Ninja": "no_history",
+            "UPU": "n/a"
+          }
+        },
         {
           "results": {
             "Ship24": "no_history",
@@ -1023,7 +1088,8 @@
             "17TRACK": "no_history",
             "Postal Ninja": "refused",
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -1046,8 +1112,18 @@
     {
       "carrier": "packeta",
       "direct": "Yes",
-      "sample": "No history",
+      "sample": "✓ 6",
       "references": [
+        {
+          "note": "A parcel handed to a delivery partner",
+          "results": {
+            "Ship24": 11,
+            "ParcelsApp": "no_history",
+            "17TRACK": "no_history",
+            "Postal Ninja": 12,
+            "UPU": "n/a"
+          }
+        },
         {
           "stale": true,
           "results": {
@@ -1056,7 +1132,8 @@
             "17TRACK": "no_history",
             "Postal Ninja": "no_history",
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -1086,9 +1163,10 @@
     {
       "carrier": "bring-posten",
       "direct": "Yes",
-      "sample": "Not tested; alternate ✓ 3",
+      "sample": "✓ 12",
       "references": [
         {
+          "note": "A Norwegian postal item",
           "results": {
             "Ship24": 12,
             "ParcelsApp": 15,
@@ -1096,6 +1174,16 @@
             "Postal Ninja": 16,
             "UPU": 3
           }
+        },
+        {
+          "results": {
+            "Ship24": 12,
+            "ParcelsApp": 15,
+            "17TRACK": 19,
+            "Postal Ninja": 16,
+            "UPU": 3
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -1166,9 +1254,10 @@
     {
       "carrier": "brt",
       "direct": "Yes",
-      "sample": "Not tested; alternate ✓ 7",
+      "sample": "✓ 9",
       "references": [
         {
+          "note": "An international parcel",
           "results": {
             "Ship24": "no_history",
             "ParcelsApp": 23,
@@ -1176,6 +1265,16 @@
             "Postal Ninja": 5,
             "UPU": "n/a"
           }
+        },
+        {
+          "results": {
+            "Ship24": "no_history",
+            "ParcelsApp": 23,
+            "17TRACK": "no_history",
+            "Postal Ninja": 5,
+            "UPU": "n/a"
+          },
+          "note": "Another comparison reference"
         }
       ]
     },
@@ -1214,8 +1313,18 @@
     {
       "carrier": "mrw",
       "direct": "Yes",
-      "sample": "Summary only; alternate ✓ 14",
+      "sample": "✓ 14",
       "references": [
+        {
+          "note": "A delivered parcel",
+          "results": {
+            "Ship24": 14,
+            "ParcelsApp": 14,
+            "17TRACK": "no_history",
+            "Postal Ninja": 14,
+            "UPU": "n/a"
+          }
+        },
         {
           "stale": true,
           "results": {
@@ -1224,7 +1333,8 @@
             "17TRACK": 1,
             "Postal Ninja": "no_history",
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         },
         {
           "note": "A September parcel",
@@ -1240,8 +1350,18 @@
     {
       "carrier": "nacex",
       "direct": "Yes",
-      "sample": "Not tested; alternate ✓ 14",
+      "sample": "✓ 13",
       "references": [
+        {
+          "note": "An agency/shipment reference",
+          "results": {
+            "Ship24": "refused",
+            "ParcelsApp": "refused",
+            "17TRACK": "refused",
+            "Postal Ninja": "refused",
+            "UPU": "n/a"
+          }
+        },
         {
           "results": {
             "Ship24": "error",
@@ -1249,7 +1369,8 @@
             "17TRACK": "error",
             "Postal Ninja": "error",
             "UPU": "n/a"
-          }
+          },
+          "note": "Another comparison reference"
         }
       ]
     },

package/dist/server/openapi.json

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

package/package.json

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