universal-parcel-scraper 0.35.1-main.386 → 0.36.0

package/dist/core/transport/trawl.d.ts

@@ -30,6 +30,8 @@ export interface TrawlCapturedResponse {
     truncated: boolean;
     base64Encoded: boolean;
     error: string | null;
+    /** 17TRACK's matching browser request included the supplied delivery postcode. */
+    postcodeSubmitted?: boolean;
 }
 export interface TrawlScrapeResponse {
     url: string;

package/dist/core/transport/trawl.js

@@ -70,6 +70,7 @@ function captured(value) {
         truncated: entry.truncated === true,
         base64Encoded: entry.base64Encoded === true,
         error: typeof entry.error === 'string' ? entry.error : entry.error ? 'error' : null,
+        ...(entry.postcodeSubmitted === true ? { postcodeSubmitted: true } : {}),
     }));
 }
 /**

package/dist/providers/seventeentrack/adapter.d.ts

@@ -25,7 +25,7 @@ export declare class SeventeenTrackVerificationError extends ChallengeError {
 }
 /** Structured replies without usable history; polling may still produce a later success. */
 export declare function isSeventeenTrackLookupError(error: unknown): error is SeventeenTrackLookupError | SeventeenTrackNoHistoryError | SeventeenTrackVerificationError;
-export declare function parse17TrackResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare function parse17TrackResponse(payload: unknown, trackingNumber: string, postcode?: string | null): CarrierResult;
 export interface SeventeenTrackOptions {
     trawl?: TrawlClient | null;
     fetcher?: typeof fetch;
@@ -35,6 +35,6 @@ export interface SeventeenTrackOptions {
 export declare class SeventeenTrackTracker {
     readonly options: SeventeenTrackOptions;
     constructor(options?: SeventeenTrackOptions);
-    fetch(trackingNumber: string, budgetMs?: number, signal?: AbortSignal): Promise<CarrierResult>;
+    fetch(trackingNumber: string, budgetMs?: number, signal?: AbortSignal, postcode?: string | null): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/providers/seventeentrack/adapter.js

@@ -9,7 +9,7 @@
  * verification wall from an outage.
  */
 import { DateTime } from 'luxon';
-import { ChallengeError, NoHistoryError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { ChallengeError, InputRequiredError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { isRecord } from '../../core/types.js';
 import { universalCarrierHints } from '../shared/hints.js';
@@ -75,7 +75,13 @@ function facilityWall(raw) {
     return clock && typeof clock.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(clock.date)
         && typeof clock.time === 'string' && /^\d{2}:\d{2}:\d{2}$/.test(clock.time) ? `${clock.date}T${clock.time}` : null;
 }
-export function parse17TrackResponse(payload, trackingNumber) {
+function requestsPostcode(shipment) {
+    if (Array.isArray(shipment.params_v2))
+        return shipment.params_v2.some(p => isRecord(p) && p.key === 'postal_code');
+    return (isRecord(shipment.param) && shipment.param.type === 'PostalCode')
+        || (Array.isArray(shipment.params) && shipment.params.some(p => isRecord(p) && p.type === 'PostalCode'));
+}
+export function parse17TrackResponse(payload, trackingNumber, postcode = null) {
     const number = numberOf(trackingNumber);
     if (!isRecord(payload) || !isRecord(payload.meta) || !Number.isInteger(payload.meta.code)) {
         throw new SchemaError(SOURCE, '17TRACK lookup unavailable');
@@ -94,8 +100,11 @@ export function parse17TrackResponse(payload, trackingNumber) {
         const code = Number(matches[0].code);
         // Observed repeatedly for valid references whose other providers have history.
         // Scope this to the matching shipment; envelope errors and unknown shapes remain failures.
-        if (code === 400 && matches[0].shipment === null)
+        if (code === 400 && matches[0].shipment === null) {
+            if (!postcode && requestsPostcode(matches[0]))
+                throw new InputRequiredError(SOURCE, 'postcode');
             throw new SeventeenTrackNoHistoryError();
+        }
         throw new SeventeenTrackLookupError(code === 100 ? 'lookup_pending' : 'lookup_unavailable', code);
     }
     if (matches.length !== 1 || !isRecord(matches[0]) || matches[0].code !== 200 || !isRecord(matches[0].shipment)) {
@@ -156,10 +165,14 @@ export class SeventeenTrackTracker {
     constructor(options = {}) {
         this.options = options;
     }
-    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? 30_000, signal) {
+    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? 30_000, signal, postcode = null) {
         const number = numberOf(trackingNumber);
+        postcode = postcode?.trim().replace(/\s+/g, ' ').toUpperCase() || null;
+        if (postcode && (postcode.length < 2 || postcode.length > 15 || !/^[A-Z0-9]+(?:[ -][A-Z0-9]+)*$/.test(postcode))) {
+            throw new InvalidInputError(SOURCE, '17TRACK delivery postcode has an invalid format');
+        }
         const spec = (remainingMs, signal) => ({
-            source: SOURCE, url: `https://t.17track.net/en#nums=${number}`, apiUrl: API_URL,
+            source: SOURCE, url: `https://t.17track.net/en#nums=${number}${postcode ? `&trawl-postcode=${encodeURIComponent(postcode)}` : ''}`, apiUrl: API_URL,
             budgetMs: remainingMs, fetcher: this.options.fetcher, signal,
         });
         return runSteps({ carrier: SOURCE, budgetMs, signal, recorder: this.options.recorder }, [{
@@ -170,12 +183,28 @@ export class SeventeenTrackTracker {
                     let pending;
                     for (const body of capturedBodies(page, capture)) {
                         try {
-                            return parse17TrackResponse(JSON.parse(body), number);
+                            const payload = JSON.parse(body);
+                            // Old browser-service builds ignore the private input marker. Never
+                            // report that a supplied postcode was tried without a bound request.
+                            const submitted = page.capturedResponses.some(entry => entry.body === body && entry.postcodeSubmitted === true);
+                            if (postcode && !submitted) {
+                                try {
+                                    return parse17TrackResponse(payload, number);
+                                }
+                                catch (error) {
+                                    if (error instanceof InputRequiredError || error instanceof SeventeenTrackNoHistoryError) {
+                                        throw new TransportError(SOURCE, '17TRACK browser service did not submit the delivery postcode', { reason: 'postcode_not_submitted' });
+                                    }
+                                    throw error;
+                                }
+                            }
+                            return parse17TrackResponse(payload, number, postcode);
                         }
                         catch (error) {
                             // Continue past polling replies and unrelated/demo numbers, but retain
                             // the latest structured failure if no matching history follows.
-                            if (isSeventeenTrackLookupError(error) || error instanceof NotFoundError || error instanceof SchemaError)
+                            if (isSeventeenTrackLookupError(error) || error instanceof NotFoundError || error instanceof SchemaError
+                                || error instanceof InputRequiredError || error instanceof TransportError)
                                 pending ??= error;
                         }
                     }
@@ -191,6 +220,6 @@ export const adapter = (environment) => {
     return {
         id: SOURCE,
         steps: ['trawl'],
-        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, context?.signal),
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, context?.signal, input.postcode),
     };
 };

package/dist/providers/universal.d.ts

@@ -55,7 +55,7 @@ export declare class UniversalTracker {
      * Look up one number through the whole chain. `postcode` is the parcel's
      * stored delivery postcode, if the user supplied one: it is forwarded into
      * every provider's track input. ParcelsApp submits it as extra[zipcode] on
-     * its direct API request; the other providers currently do not consume it.
+     * its direct API request; 17TRACK submits it through the browser's postcode form.
      * `countryHint` lets ParcelsApp retry an empty answer with that country.
      * The caller's budget covers the whole chain and its signal ends it.
      */

package/dist/providers/universal.js

@@ -48,7 +48,7 @@ export class UniversalTracker {
      * Look up one number through the whole chain. `postcode` is the parcel's
      * stored delivery postcode, if the user supplied one: it is forwarded into
      * every provider's track input. ParcelsApp submits it as extra[zipcode] on
-     * its direct API request; the other providers currently do not consume it.
+     * its direct API request; 17TRACK submits it through the browser's postcode form.
      * `countryHint` lets ParcelsApp retry an empty answer with that country.
      * The caller's budget covers the whole chain and its signal ends it.
      */

package/dist/server/openapi.json

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

package/package.json

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