universal-parcel-scraper 0.2.0 → 0.3.0-main.298

package/dist/carriers/heppner/adapter.js

@@ -16,8 +16,9 @@
  */
 import { Buffer } from 'node:buffer';
 import { DateTime } from 'luxon';
-import { InputRequiredError, NotFoundError, SchemaError } from '../../core/errors/index.js';
-import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { lookupBudget } from '../../core/adapter/index.js';
+import { InputRequiredError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf, } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyHeppnerEvent, heppnerCode } from './status.js';
 const SEARCH_ENDPOINT = 'https://myportal.heppner-group.com/api/recipient/search/expedition';
@@ -43,7 +44,7 @@ function eventTime(value) {
 export function normalizeHeppnerTrackingNumber(raw) {
     const trackingNumber = raw.replace(/\s/g, '');
     if (!/^\d{8}$/.test(trackingNumber)) {
-        throw new TypeError('Heppner tracking numbers must contain exactly 8 digits');
+        throw new InvalidInputError('Heppner', 'Heppner tracking numbers must contain exactly 8 digits');
     }
     return trackingNumber;
 }
@@ -51,7 +52,7 @@ export function normalizeHeppnerCredential(rawTrackingNumber, rawPostcode) {
     const trackingNumber = normalizeHeppnerTrackingNumber(rawTrackingNumber);
     const postcode = rawPostcode.trim();
     if (!/^\d{4,5}$/.test(postcode)) {
-        throw new TypeError('Heppner requires a four-digit Swiss or five-digit French delivery postcode');
+        throw new InvalidInputError('Heppner', 'Heppner requires a four-digit Swiss or five-digit French delivery postcode');
     }
     return {
         trackingNumber,
@@ -178,30 +179,33 @@ export function parseHeppnerTrackingResponse(payload, rawTrackingNumber) {
         events: parsed.map(({ event }) => event),
     };
 }
-function requestHeaders(accept, origin = 'https://www.heppner-group.com') {
+function requestHeaders(userAgent, accept, origin = 'https://www.heppner-group.com') {
     return {
         Accept: accept,
         'Accept-Language': 'fr-FR,fr;q=0.9',
         Origin: origin,
         Referer: 'https://www.heppner-group.com/destinataire-suivez-votre-marchandise/',
-        'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+        'User-Agent': userAgent,
     };
 }
 export class HeppnerTracker {
     timeoutMs;
     fetcher;
+    userAgent;
     constructor(options = {}) {
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.fetcher = options.fetcher;
         if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
             throw new TypeError('Heppner timeout must be positive');
         }
+        this.userAgent = userAgentOf(options.userAgent);
     }
-    async fetch(rawTrackingNumber, rawPostcode) {
+    async fetch(rawTrackingNumber, rawPostcode, context = {}) {
         const credential = normalizeHeppnerCredential(rawTrackingNumber, rawPostcode);
-        const search = await fetchBounded(heppnerSearchUrl(credential.trackingNumber, credential.postcode), { headers: requestHeaders('text/plain,*/*;q=0.8') }, {
+        const budget = lookupBudget(context, 2 * this.timeoutMs);
+        const search = await fetchBounded(heppnerSearchUrl(credential.trackingNumber, credential.postcode), { signal: budget.signal, headers: requestHeaders(this.userAgent, 'text/plain,*/*;q=0.8') }, {
             provider: 'Heppner shipment search',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: 2_048,
             fetcher: this.fetcher,
             allowHttpError: true,
@@ -213,13 +217,14 @@ export class HeppnerTracker {
         }
         const capability = parseHeppnerCapability(decodeText(search.bytes), credential.trackingNumber, credential.postcode);
         const detail = await fetchBounded(heppnerDetailUrl(capability), {
+            signal: budget.signal,
             headers: {
-                ...requestHeaders('application/json', 'https://myportal.heppner-group.com'),
+                ...requestHeaders(this.userAgent, 'application/json', 'https://myportal.heppner-group.com'),
                 Referer: heppnerTrackingPageUrl(capability),
             },
         }, {
             provider: 'Heppner tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             fetcher: this.fetcher,
             allowHttpError: true,
@@ -233,15 +238,15 @@ export class HeppnerTracker {
     }
 }
 export const adapter = (environment) => {
-    const tracker = new HeppnerTracker({ fetcher: environment.fetcher });
+    const tracker = new HeppnerTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'heppner',
         steps: ['direct'],
-        track: async (input) => {
+        track: async (input, context) => {
             const postcode = input.postcode?.trim() ?? '';
             if (!postcode)
                 throw new InputRequiredError('Heppner', 'the delivery postcode');
-            return tracker.fetch(input.number, postcode);
+            return tracker.fetch(input.number, postcode, context);
         },
     };
 };

package/dist/carriers/heppner/carrier.json

@@ -20,7 +20,7 @@
     "adapter": "heppner",
     "requirements": [
       {
-        "field": "dpdPostcode",
+        "field": "postcode",
         "validator": "swissOrFrancePostcode",
         "label": "Delivery postcode",
         "type": "text",

package/dist/carriers/hermes/adapter.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterFactory } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import { hermesStatus } from './status.js';
 export { hermesStatus };
@@ -6,12 +6,13 @@ export interface HermesOptions {
     timeoutMs?: number;
     /** Test seam; production uses the global fetch. */
     fetcher?: typeof fetch;
+    userAgent?: string;
 }
 export declare function parseHermesTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
 export declare class HermesTracker {
     #private;
     readonly timeoutMs: number;
     constructor(options?: number | HermesOptions);
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/hermes/adapter.js

@@ -1,5 +1,6 @@
+import { lookupBudget } from '../../core/adapter/index.js';
 import { NotFoundError, SchemaError } from '../../core/errors/index.js';
-import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { hermesEventStage, hermesStatus } from './status.js';
 export { hermesStatus };
@@ -70,34 +71,38 @@ export function parseHermesTrackingResponse(payload, trackingNumber) {
 export class HermesTracker {
     timeoutMs;
     #fetcher;
+    #userAgent;
     constructor(options = {}) {
-        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher } = typeof options === 'number'
-            ? { timeoutMs: options, fetcher: undefined }
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher, userAgent } = typeof options === 'number'
+            ? { timeoutMs: options, fetcher: undefined, userAgent: undefined }
             : options;
         this.timeoutMs = timeoutMs;
         this.#fetcher = fetcher;
+        this.#userAgent = userAgentOf(userAgent);
     }
-    async fetch(trackingNumber) {
+    async fetch(trackingNumber, context = {}) {
         const url = new URL(HERMES_API);
         url.searchParams.set('parcelNumber', trackingNumber);
+        const budget = lookupBudget(context, this.timeoutMs);
         const { bytes } = await fetchBounded(url, {
+            signal: budget.signal,
             headers: {
                 Accept: 'application/json',
-                'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+                'User-Agent': this.#userAgent,
             },
         }, {
             provider: 'Hermes tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
         });
         return parseHermesTrackingResponse(parseJsonBytes(bytes, PROVIDER), trackingNumber);
     }
 }
 export const adapter = (environment) => {
-    const tracker = new HermesTracker({ fetcher: environment.fetcher });
+    const tracker = new HermesTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'hermes',
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/hermes-de/adapter.d.ts

@@ -1,10 +1,11 @@
-import { type AdapterFactory } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import { NotFoundError } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 export interface HermesGermanyOptions {
     timeoutMs?: number;
     /** Test seam; production uses the global fetch. */
     fetcher?: typeof fetch;
+    userAgent?: string;
 }
 export { STATUSES } from './status.js';
 /** Kept as a named class: the grouped live suite asserts this error's name. */
@@ -17,6 +18,6 @@ export declare class HermesGermanyTracker {
     #private;
     readonly timeoutMs: number;
     constructor(options?: number | HermesGermanyOptions);
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/hermes-de/adapter.js

@@ -1,7 +1,7 @@
 import { DateTime } from 'luxon';
-import { recognizeFromLookup } from '../../core/adapter/index.js';
-import { InputRequiredError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
-import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
+import { InvalidInputError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { clean, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { hermesGermanyMilestone, IGNORED_BOOKING_STATUS } from './status.js';
 // Public recipient protocol inspected 2026-09-08:
@@ -36,7 +36,7 @@ export class HermesGermanyTrackingError extends NotFoundError {
 export function normalizeHermesGermanyNumber(raw) {
     const value = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^(?=.*\d)[A-Z0-9]{8,20}$/.test(value)) {
-        throw new InputRequiredError(CARRIER, 'an 8-to-20-character tracking number', 'Hermes Germany requires an 8-to-20-character tracking number');
+        throw new InvalidInputError(CARRIER, 'Hermes Germany requires an 8-to-20-character tracking number');
     }
     return value;
 }
@@ -125,27 +125,31 @@ export function parseHermesGermanyResponse(payload, trackingNumber) {
 export class HermesGermanyTracker {
     timeoutMs;
     #fetcher;
+    #userAgent;
     constructor(options = {}) {
-        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher } = typeof options === 'number'
-            ? { timeoutMs: options, fetcher: undefined }
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher, userAgent } = typeof options === 'number'
+            ? { timeoutMs: options, fetcher: undefined, userAgent: undefined }
             : options;
         if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
             throw new TypeError('Hermes Germany timeout must be positive');
         this.timeoutMs = timeoutMs;
         this.#fetcher = fetcher;
+        this.#userAgent = userAgentOf(userAgent);
     }
-    async fetch(trackingNumber) {
+    async fetch(trackingNumber, context = {}) {
         const number = normalizeHermesGermanyNumber(trackingNumber);
+        const budget = lookupBudget(context, this.timeoutMs);
         const { response, bytes } = await fetchBounded(`${API}${encodeURIComponent(number)}`, {
+            signal: budget.signal,
             headers: {
                 Accept: 'application/json',
                 'X-Language': 'de',
                 Referer: 'https://www.myhermes.de/',
-                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+                'User-Agent': this.#userAgent,
             },
         }, {
             provider: PROVIDER,
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: 750_000,
             allowHttpError: true,
             ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
@@ -158,11 +162,11 @@ export class HermesGermanyTracker {
     }
 }
 export const adapter = (environment) => {
-    const tracker = new HermesGermanyTracker({ fetcher: environment.fetcher });
+    const tracker = new HermesGermanyTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'hermes-de',
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
-        recognize: (number) => recognizeFromLookup(() => tracker.fetch(number)),
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context)),
     };
 };

package/dist/carriers/india-post/adapter.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterFactory } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import { ChallengeError } from '../../core/errors/index.js';
 import { type CarrierResult } from '../../core/result/index.js';
 import { classifyIndiaPostEvent } from './status.js';
@@ -26,7 +26,7 @@ export declare class IndiaPostTracker {
     constructor(options?: IndiaPostTrackerOptions);
     private request;
     private update;
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
     /** Send the first calls, then poll `fetchStatus` until the component completes. */
     private complete;
 }

package/dist/carriers/india-post/adapter.js

@@ -1,7 +1,8 @@
 import { load } from 'cheerio';
 import makeFetchCookie from 'fetch-cookie';
 import { CookieJar } from 'tough-cookie';
-import { ChallengeError, IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { lookupBudget } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { eventPoint } from '../../core/result/index.js';
 import { isValidS10TrackingNumber } from '../../core/detection/index.js';
 import { isoTime } from '../../core/time/index.js';
@@ -38,7 +39,7 @@ export class IndiaPostChallengeError extends ChallengeError {
 export function normalizeIndiaPostTrackingNumber(raw) {
     const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
     if (!/^[A-Z]{2}\d{9}IN$/.test(value) || !isValidS10TrackingNumber(value)) {
-        throw new TypeError('India Post tracking requires a valid 13-character S10 number ending in IN');
+        throw new InvalidInputError('India Post', 'India Post tracking requires a valid 13-character S10 number ending in IN');
     }
     return value;
 }
@@ -261,10 +262,22 @@ function challengePage(status, html, headers) {
         || headers.get('cf-mitigated') === 'challenge'
         || /Just a moment|Enable JavaScript and cookies|cf-chl-|_cf_chl_opt/i.test(html);
 }
-function pause(milliseconds) {
-    return milliseconds > 0
-        ? new Promise((resolve) => setTimeout(resolve, milliseconds))
-        : Promise.resolve();
+/** The poll interval, cut short as soon as the lookup's signal aborts. */
+async function pause(milliseconds, signal) {
+    signal.throwIfAborted();
+    if (milliseconds <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', abort);
+            resolve();
+        }, milliseconds);
+        signal.addEventListener('abort', abort, { once: true });
+    });
 }
 export class IndiaPostTracker {
     timeoutMs;
@@ -288,10 +301,10 @@ export class IndiaPostTracker {
             throw new TypeError('India Post poll attempts must be positive');
         }
     }
-    async request(fetcher, url, init) {
-        const result = await fetchBounded(url, init, {
+    async request(fetcher, budget, url, init) {
+        const result = await fetchBounded(url, { ...init, signal: budget.signal }, {
             provider: 'India Post tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             redirect: 'manual',
             fetcher,
@@ -306,8 +319,8 @@ export class IndiaPostTracker {
         }
         return { bytes: result.bytes, html };
     }
-    async update(fetcher, trackingNumber, pageUrl, token, snapshot, calls, updates = {}) {
-        const result = await this.request(fetcher, LIVEWIRE_UPDATE, {
+    async update(fetcher, budget, trackingNumber, pageUrl, token, snapshot, calls, updates = {}) {
+        const result = await this.request(fetcher, budget, LIVEWIRE_UPDATE, {
             method: 'POST',
             headers: {
                 Accept: 'application/json',
@@ -325,13 +338,16 @@ export class IndiaPostTracker {
         });
         return parseLivewireUpdate(parseJsonBytes(result.bytes, 'India Post tracking'), trackingNumber);
     }
-    async fetch(trackingNumber) {
+    async fetch(trackingNumber, context = {}) {
         const normalized = normalizeIndiaPostTrackingNumber(trackingNumber);
         const pageUrl = indiaPostTrackingUrl(normalized);
+        // The default budget covers the page, the first update, then every poll
+        // after its pause.
+        const budget = lookupBudget(context, (this.maxPollAttempts + 2) * this.timeoutMs + this.maxPollAttempts * this.pollIntervalMs);
         // The Livewire flow is stateful: the session cookie issued with the page
         // must travel with every /livewire/update call, so the jar is per lookup.
         const fetcher = makeFetchCookie(this.fetcher, new CookieJar());
-        const page = await this.request(fetcher, pageUrl, {
+        const page = await this.request(fetcher, budget, pageUrl, {
             headers: {
                 Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
                 'Accept-Language': 'en-US,en;q=0.9',
@@ -347,13 +363,18 @@ export class IndiaPostTracker {
             // What the page's Refresh button sends. A failed refresh still leaves
             // the cached history, which is better than no answer.
             try {
-                return await this.complete(fetcher, normalized, pageUrl, csrfToken(page.html), initial.snapshot, [{
+                return await this.complete(fetcher, budget, normalized, pageUrl, csrfToken(page.html), initial.snapshot, [{
                         path: '',
                         method: '__dispatch',
                         params: ['refresh_consignment', { userTimezone: USER_TIMEZONE }],
                     }], { userTimezone: USER_TIMEZONE });
             }
             catch {
+                // A caller that cancelled is not waiting for an answer; one whose
+                // deadline passed still takes the history already in hand.
+                const reason = context.signal?.reason;
+                if (context.signal?.aborted && !(reason instanceof DOMException && reason.name === 'TimeoutError'))
+                    throw reason;
                 return cached;
             }
         }
@@ -362,12 +383,12 @@ export class IndiaPostTracker {
         }
         const token = csrfToken(page.html);
         return initial.status === 'Processing'
-            ? this.complete(fetcher, normalized, pageUrl, token, initial.snapshot, [{
+            ? this.complete(fetcher, budget, normalized, pageUrl, token, initial.snapshot, [{
                     path: '',
                     method: 'fetchStatus',
                     params: [],
                 }])
-            : this.complete(fetcher, normalized, pageUrl, token, initial.snapshot, [{
+            : this.complete(fetcher, budget, normalized, pageUrl, token, initial.snapshot, [{
                     path: '',
                     method: '__dispatch',
                     params: ['set_consignment_number', { consignment_number: normalized }],
@@ -378,8 +399,8 @@ export class IndiaPostTracker {
                 }], { userTimezone: USER_TIMEZONE });
     }
     /** Send the first calls, then poll `fetchStatus` until the component completes. */
-    async complete(fetcher, normalized, pageUrl, token, snapshot, calls, updates = {}) {
-        let update = await this.update(fetcher, normalized, pageUrl, token, snapshot, calls, updates);
+    async complete(fetcher, budget, normalized, pageUrl, token, snapshot, calls, updates = {}) {
+        let update = await this.update(fetcher, budget, normalized, pageUrl, token, snapshot, calls, updates);
         for (let attempt = 0; attempt <= this.maxPollAttempts; attempt += 1) {
             const names = dispatchNames(update.effects);
             if (names.has('consignment_not_found'))
@@ -395,8 +416,8 @@ export class IndiaPostTracker {
             }
             if (attempt === this.maxPollAttempts)
                 break;
-            await pause(this.pollIntervalMs);
-            update = await this.update(fetcher, normalized, pageUrl, token, update.component.snapshot, [{ path: '', method: 'fetchStatus', params: [] }]);
+            await pause(this.pollIntervalMs, budget.signal);
+            update = await this.update(fetcher, budget, normalized, pageUrl, token, update.component.snapshot, [{ path: '', method: 'fetchStatus', params: [] }]);
         }
         // The backend kept saying "Processing": it answered, but it proved nothing
         // about the shipment, so this must not become a not-found cooldown.
@@ -410,6 +431,6 @@ export const adapter = (environment) => {
         // The Livewire submit-and-poll cycle is part of the direct call: it is one
         // stateful conversation with one host, not a fallback tier.
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/inpost/adapter.d.ts

@@ -1,14 +1,16 @@
-import { type AdapterFactory } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 export declare function normalizeInpostTrackingNumber(raw: string): string;
 export declare function parseInpostTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
 export declare class InpostTracker {
     readonly timeoutMs: number;
     readonly fetcher: typeof fetch | undefined;
+    private readonly userAgent;
     constructor(options?: {
         timeoutMs?: number;
         fetcher?: typeof fetch;
+        userAgent?: string;
     });
-    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/inpost/adapter.js

@@ -1,7 +1,7 @@
-import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
-import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { accepted, lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
+import { InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
-import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError } from '../../core/transport/index.js';
+import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyInpostStatus } from './status.js';
 // Protocol provenance:
@@ -20,6 +20,8 @@ import { classifyInpostStatus } from './status.js';
 //   consignments 2026-08-31 by the prior-art client; the map 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. */
+const TRANSIENT_RETRY_DELAY_MS = 1_000;
 const MAX_RESPONSE_BYTES = 1_000_000;
 const MAX_EVENTS_TO_RETURN = 20;
 function statusCode(value) {
@@ -28,7 +30,7 @@ function statusCode(value) {
 export function normalizeInpostTrackingNumber(raw) {
     const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
     if (!/^(?:\d{24}|JJD\d{16}|JD\d{16}|8YDR\d{9})$/.test(value)) {
-        throw new TypeError('InPost tracking requires a 24-digit, JJD/JD legacy or 8YDR identifier');
+        throw new InvalidInputError('InPost', 'InPost tracking requires a 24-digit, JJD/JD legacy or 8YDR identifier');
     }
     return value;
 }
@@ -101,25 +103,30 @@ export function parseInpostTrackingResponse(payload, trackingNumber) {
 export class InpostTracker {
     timeoutMs;
     fetcher;
+    userAgent;
     constructor(options = {}) {
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.fetcher = options.fetcher;
+        this.userAgent = userAgentOf(options.userAgent);
         if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
             throw new TypeError('InPost timeout must be positive');
         }
     }
-    async fetch(rawTrackingNumber) {
+    async fetch(rawTrackingNumber, context = {}) {
         const trackingNumber = normalizeInpostTrackingNumber(rawTrackingNumber);
+        // The default budget covers the request, the pause and the one transient retry.
+        const budget = lookupBudget(context, 2 * this.timeoutMs + TRANSIENT_RETRY_DELAY_MS);
         const url = `${TRACKING_ENDPOINT}/${encodeURIComponent(trackingNumber)}`;
         const { response, bytes } = await fetchBounded(url, {
+            signal: budget.signal,
             headers: {
                 Accept: 'application/json, text/plain, */*',
                 'Accept-Language': 'en-US,en;q=0.9',
-                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+                'User-Agent': this.userAgent,
             },
         }, {
             provider: 'InPost tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
             allowHttpError: true,
@@ -133,11 +140,11 @@ export class InpostTracker {
     }
 }
 export const adapter = (environment) => {
-    const tracker = new InpostTracker({ fetcher: environment.fetcher });
+    const tracker = new InpostTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'inpost',
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
-        recognize: (number) => recognizeFromLookup(() => tracker.fetch(number), () => accepted(() => normalizeInpostTrackingNumber(number))),
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeInpostTrackingNumber(number))),
     };
 };

package/dist/carriers/japan-post/adapter.js

@@ -1,7 +1,7 @@
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
-import { ChallengeError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { ChallengeError, InvalidInputError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
 import { japanPostStatus } from './status.js';
 const PROVIDER = 'Japan Post';
@@ -19,7 +19,7 @@ export function normalizeJapanPostNumber(raw) {
     // S10 references. U-prefixed customs labels are explicitly not trackable.
     if (!/^\d{11,13}$/.test(number)
         && (!/^[A-TV-Z][A-Z]\d{9}[A-Z]{2}$/.test(number) || !isValidS10TrackingNumber(number))) {
-        throw new InputRequiredError(PROVIDER, 'number', 'Japan Post requires a domestic tracking number or a valid tracked postal reference');
+        throw new InvalidInputError(PROVIDER, 'Japan Post requires a domestic tracking number or a valid tracked postal reference');
     }
     return number;
 }

package/dist/carriers/korea-post/adapter.js

@@ -1,6 +1,6 @@
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
-import { IndeterminateError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
 import { koreaPostStatus } from './status.js';
@@ -8,7 +8,7 @@ const ENDPOINT = 'https://trace.epost.go.kr/xtts/servlet/kpl.tts.common.svl.SttS
 export function normalizeKoreaPostNumber(raw) {
     const number = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^[A-Z]{2}\d{9}[A-Z]{2}$/.test(number))
-        throw new InputRequiredError('Korea Post', 'number', 'Korea Post direct tracking supports international postal identifiers');
+        throw new InvalidInputError('Korea Post', 'Korea Post direct tracking supports international postal identifiers');
     return number;
 }
 function eventTime(raw) {

package/dist/carriers/la-poste/adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AdapterFactory } from '../../core/adapter/index.js';
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import { CarrierError } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import type { StepRecorder } from '../../core/telemetry/index.js';
@@ -18,12 +18,14 @@ export interface LaPosteTrackerOptions {
     timeoutMs?: number;
     fetcher?: typeof fetch;
     recorder?: StepRecorder;
+    userAgent?: string;
 }
 export declare class LaPosteTracker {
     readonly timeoutMs: number;
     private readonly fetcher?;
     private readonly recorder?;
+    private readonly userAgent;
     constructor(options?: LaPosteTrackerOptions);
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;