universal-parcel-scraper 0.3.0 → 0.3.1-main.312

package/README.md

@@ -6,7 +6,7 @@
 
 **Parcel tracking that asks the carrier directly, from your own machine.**
 
-The engine behind [Peek](https://github.com/plhery/delivery-tracker), the open-source parcel tracker for iPhone and the web.
+The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/plhery/peek-delivery-tracker)), the open-source parcel tracker for iPhone and the web.
 
 [![npm](https://img.shields.io/npm/v/universal-parcel-scraper)](https://www.npmjs.com/package/universal-parcel-scraper)
 [![CI](https://github.com/plhery/universal-parcel-scraper/actions/workflows/ci.yml/badge.svg)](https://github.com/plhery/universal-parcel-scraper/actions/workflows/ci.yml)
@@ -27,7 +27,7 @@ The engine behind [Peek](https://github.com/plhery/delivery-tracker), the open-s
 Give it a tracking number. It finds the carrier, fetches the history from the carrier's own
 site and returns the same JSON for every carrier. No account, no API key.
 
-It is the tracking engine of [Peek](https://github.com/plhery/delivery-tracker), usable on
+It is the tracking engine of [Peek](https://github.com/plhery/peek-delivery-tracker), usable on
 its own as a command, a Node library or an HTTP server.
 
 ## Benchmark
@@ -120,7 +120,7 @@ settings, such as `SCRAPER_TOKEN` and `SCRAPER_TRUSTED_PROXIES`, in [.env.exampl
 
 ## What you can build with it
 
-- A parcel-tracking app, like [Peek](https://github.com/plhery/delivery-tracker).
+- A parcel-tracking app, like [Peek](https://github.com/plhery/peek-delivery-tracker).
 - A [Home Assistant sensor](examples/home-assistant.yaml) for the parcel you are waiting on.
 - Order status inside a shop or help desk, from any backend that speaks HTTP.
 - Tracking numbers pulled out of shipping emails: `detect` reads pasted text and links.

package/dist/app.d.ts

@@ -8,7 +8,7 @@
 export * from './core/catalog/parcel.js';
 export * from './core/catalog/hints.js';
 export * from './core/time/result.js';
-export { sameInstantIdentityPolicy, type SameInstantIdentityPolicy } from './core/catalog/eventIdentity.js';
+export { sameInstantIdentityPolicy, type SameInstantIdentityPolicy, type SameInstantScan } from './core/catalog/eventIdentity.js';
 export { universalCarrierHints } from './providers/shared/hints.js';
 export { recognitionAskedCarriers } from './core/catalog/recognition.js';
 export { countryFlag, countryName, trackingLocationCountry, trackingPlace, type TrackingPlace } from './places/trackingLocation.js';

package/dist/carriers/ctt/adapter.js

@@ -2,7 +2,7 @@ import { lookupBudget } from '../../core/adapter/index.js';
 import { IndeterminateError, InvalidInputError, MaintenanceError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { isValidS10TrackingNumber } from '../../core/detection/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
-import { clean, decodeText, escapeRegExp, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { clean, decodeText, escapeRegExp, fetchBounded, parseJsonBytes, } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyCttStatus } from './status.js';
 // Protocol provenance:
@@ -17,8 +17,7 @@ import { classifyCttStatus } from './status.js';
 //   rotates on every frontend deploy (derived at runtime from keyless version
 //   endpoints and the screen bundle — never pinned). A browser User-Agent is
 //   mandatory (Cloudflare error 1010 otherwise).
-// - Live verification 2026-09-10, including a delivered parcel whose whole
-//   history mapped: Found:true carries ObjectEventsFromQuery; Found:false is
+// - Found:true carries ObjectEventsFromQuery; Found:false is
 //   BOTH genuine unknown and backend outage, told apart only via the sibling
 //   DataActionCheckIPLocked call (made solely on Found:false — a found parcel
 //   already proves health).
@@ -178,7 +177,10 @@ export class CttTracker {
             IPClient: '',
         }, null, true, true, budget);
         const record = isRecord(payload.data) ? payload.data.ObjectEventsFromQuery : undefined;
-        if (!isRecord(record) || !record.Found) {
+        if (!isRecord(record) || typeof record.Found !== 'boolean') {
+            throw new CttApiError('missing shipment Found flag');
+        }
+        if (!record.Found) {
             // Found:false is both genuine unknown and backend outage: a found parcel
             // already proves health, so the sibling check runs solely on negatives.
             if (await this.isMaintenance(budget))
@@ -190,6 +192,8 @@ export class CttTracker {
     async isMaintenance(budget) {
         const payload = await this.callAction(MAINTENANCE_ACTION, {}, null, true, true, budget);
         const data = isRecord(payload.data) ? payload.data : {};
+        if (typeof data.IsMaintenance !== 'boolean')
+            throw new CttApiError('missing maintenance flag');
         return data.IsMaintenance === true;
     }
     async callAction(action, variables, session, retrySession, retryVersion, budget) {
@@ -217,7 +221,7 @@ export class CttTracker {
             timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
-            allowHttpError: true,
+            allowHttpStatuses: [403],
             fetcher: this.fetcher,
         });
         if (response.status === 403) {
@@ -227,8 +231,6 @@ export class CttTracker {
             }
             throw new CttApiError('anonymous session bootstrap failed');
         }
-        if (!response.ok)
-            throw new UpstreamHttpError('CTT tracking', response.status);
         const payload = parseJsonBytes(bytes, 'CTT tracking');
         if (!isRecord(payload))
             throw new CttApiError('unexpected body (not a JSON object)');
@@ -256,7 +258,7 @@ export class CttTracker {
     async ensureModuleVersion(budget) {
         if (this.moduleVersion !== null)
             return;
-        const { response, bytes } = await fetchBounded(MODULE_VERSION_URL, {
+        const { bytes } = await fetchBounded(MODULE_VERSION_URL, {
             signal: budget.signal,
             headers: { Accept: 'application/json', 'User-Agent': BROWSER_USER_AGENT },
         }, {
@@ -264,11 +266,8 @@ export class CttTracker {
             timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
-            allowHttpError: true,
             fetcher: this.fetcher,
         });
-        if (!response.ok)
-            throw new UpstreamHttpError('CTT tracking', response.status);
         const payload = parseJsonBytes(bytes, 'CTT tracking');
         const token = isRecord(payload) && typeof payload.versionToken === 'string' ? payload.versionToken : '';
         if (!token)
@@ -297,7 +296,7 @@ export class CttTracker {
         return parseJsonBytes((await this.fetchBytes(url, budget)).bytes, 'CTT tracking');
     }
     async fetchBytes(url, budget) {
-        const { response, bytes } = await fetchBounded(url, {
+        const { bytes } = await fetchBounded(url, {
             signal: budget.signal,
             headers: { Accept: 'application/json, text/plain, */*', 'User-Agent': BROWSER_USER_AGENT },
         }, {
@@ -305,11 +304,8 @@ export class CttTracker {
             timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_SCRIPT_BYTES,
             retryTransient: true,
-            allowHttpError: true,
             fetcher: this.fetcher,
         });
-        if (!response.ok)
-            throw new UpstreamHttpError('CTT tracking', response.status);
         return { bytes };
     }
 }

package/dist/carriers/inpost/adapter.js

@@ -1,7 +1,7 @@
 import { accepted, lookupBudget, recognizeFromLookup } 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 { explicitOffsetTime } from '../../core/time/index.js';
-import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf } from '../../core/transport/index.js';
+import { clean, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyInpostStatus } from './status.js';
 // Protocol provenance:
@@ -12,12 +12,9 @@ import { classifyInpostStatus } from './status.js';
 //   (api-shipx-pl.easypack24.net, keyless, but its success shape is
 //   unconfirmed) and the inposteasy.com per-country hubs below. Only the
 //   inposteasy hub is implemented here; ShipX remains a future lead.
-// - Live verification 2026-09-10: GET
-//   https://inposteasy.com/api/tracking/000000000000000000000000 returns
-//   HTTP 404 with a structured NOT_FOUND problem body in ~0.2s, no cookies,
-//   headers or account. Long-expired corpus numbers return the same 404.
-// - Public cross-border status vocabulary live-confirmed on IT/PT/GB
-//   consignments 2026-08-31 by the prior-art client; the map lives in status.ts.
+// - Unknown or expired numbers return an identity-bound NOT_FOUND problem,
+//   optionally JSON-encoded inside the tracking-error wrapper's detail field.
+// - The public cross-border status vocabulary lives in status.ts.
 const TRACKING_ENDPOINT = 'https://inposteasy.com/api/tracking';
 const DEFAULT_TIMEOUT_MS = 15_000;
 /** The pause `fetchBounded` takes before its one retry of a failed request. */
@@ -34,6 +31,23 @@ export function normalizeInpostTrackingNumber(raw) {
     }
     return value;
 }
+function isNotFoundProblem(payload, trackingNumber) {
+    if (!isRecord(payload) || payload.status !== 404
+        || payload.instance !== `/api/tracking/${trackingNumber}`)
+        return false;
+    if (payload.type === '/errors/external/not-found' && payload.title === 'NOT_FOUND')
+        return true;
+    if (payload.type !== '/errors/external/tracking-error' || typeof payload.detail !== 'string')
+        return false;
+    try {
+        const nested = JSON.parse(payload.detail.replace(/^Tracking client failed\. /, ''));
+        return isRecord(nested) && nested.type === '/errors/external/not-found'
+            && nested.title === 'NOT_FOUND' && nested.status === 404 && nested.instance === payload.instance;
+    }
+    catch {
+        return false;
+    }
+}
 export function parseInpostTrackingResponse(payload, trackingNumber) {
     const requested = normalizeInpostTrackingNumber(trackingNumber);
     if (!isRecord(payload))
@@ -129,13 +143,19 @@ export class InpostTracker {
             timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
-            allowHttpError: true,
+            allowHttpStatuses: [404],
             fetcher: this.fetcher,
         });
-        if (response.status === 404)
-            throw new NotFoundError('InPost');
-        if (!response.ok)
-            throw new UpstreamHttpError('InPost tracking', response.status);
+        if (response.status === 404) {
+            let problem;
+            try {
+                problem = parseJsonBytes(bytes, 'InPost tracking');
+            }
+            catch { /* An HTML error page proves no shipment outcome. */ }
+            if (isNotFoundProblem(problem, trackingNumber))
+                throw new NotFoundError('InPost');
+            throw new IndeterminateError('InPost', 'InPost returned an unrecognized not-found response');
+        }
         return parseInpostTrackingResponse(parseJsonBytes(bytes, 'InPost tracking'), trackingNumber);
     }
 }

package/dist/carriers/ups/app.d.ts

@@ -0,0 +1,2 @@
+import type { SameInstantIdentityPolicy } from '../../core/catalog/eventIdentity.js';
+export declare const sameInstantIdentityPolicy: SameInstantIdentityPolicy;

package/dist/carriers/ups/app.js

@@ -0,0 +1,15 @@
+function normalized(value) {
+    return value.replace(/\s+/g, ' ').trim().toLocaleLowerCase('en-US');
+}
+// UPS can add a location later. Its wording distinguishes scans sharing a clock.
+export const sameInstantIdentityPolicy = {
+    sourceCarrierId: 'ups', storedSources: ['ups'], requireProviderCode: false,
+    matches(incoming, stored) {
+        const wording = normalized(incoming.description);
+        const location = normalized(incoming.location);
+        const savedLocation = normalized(stored.location);
+        return incoming.stage !== '' && incoming.stage !== 'unknown' && incoming.stage === stored.stage
+            && wording !== '' && wording === normalized(stored.description)
+            && (!location || !savedLocation || location === savedLocation);
+    },
+};

package/dist/core/catalog/eventIdentity.d.ts

@@ -1,8 +1,18 @@
+/** Scan evidence available to the app before it reuses a stored identity. */
+export interface SameInstantScan {
+    readonly stage: string;
+    readonly description: string;
+    readonly location: string;
+    readonly providerCode: string;
+}
 /** Carrier evidence the parcel app uses when updating a stored scan in place. */
 export interface SameInstantIdentityPolicy {
     readonly sourceCarrierId: string;
     readonly storedSources: readonly string[];
     readonly requireProviderCode: boolean;
+    readonly matches?: (incoming: SameInstantScan, stored: SameInstantScan) => boolean;
 }
 /** Unlisted sources cannot identify a reworded scan by its instant alone. */
-export declare function sameInstantIdentityPolicy(sourceCarrierId: string): SameInstantIdentityPolicy | undefined;
+export declare function sameInstantIdentityPolicy(sourceCarrierId: string, options?: {
+    supportsScanMatching?: boolean;
+}): SameInstantIdentityPolicy | undefined;

package/dist/core/catalog/eventIdentity.js

@@ -1,7 +1,10 @@
 import { sameInstantIdentityPolicy as dpd } from '../../carriers/dpd/app.js';
 import { sameInstantIdentityPolicy as indiaPost } from '../../carriers/india-post/app.js';
-const policies = new Map([dpd, indiaPost].map((policy) => [policy.sourceCarrierId, policy]));
+import { sameInstantIdentityPolicy as ups } from '../../carriers/ups/app.js';
+const policies = new Map([dpd, indiaPost, ups].map((policy) => [policy.sourceCarrierId, policy]));
 /** Unlisted sources cannot identify a reworded scan by its instant alone. */
-export function sameInstantIdentityPolicy(sourceCarrierId) {
-    return policies.get(sourceCarrierId);
+export function sameInstantIdentityPolicy(sourceCarrierId, options = {}) {
+    const policy = policies.get(sourceCarrierId);
+    // Older app versions only check the clock and provider code.
+    return policy?.matches && !options.supportsScanMatching ? undefined : policy;
 }

package/dist/server/openapi.json

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

package/package.json

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