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

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

@@ -12,19 +12,21 @@
  * only when `mailNoSource` is `EXTERNAL`; otherwise Cainiao is still waiting
  * for the seller and the parcel is simply pending.
  */
-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';
 /** Projects one `detail.json` payload. Pure: the offline tests target this. */
 export declare function parseCainiaoTrackingResponse(value: unknown, trackingNumber: string): CarrierResult;
 export declare class CainiaoTracker {
     private readonly fetcher;
     private readonly timeoutMs;
+    private readonly userAgent;
     constructor(options?: {
         fetcher?: typeof fetch;
         timeoutMs?: number;
+        userAgent?: string;
     });
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 /** Kept for the host's legacy dispatch chain until it is deleted. */
-export declare function fetchCainiao(trackingNumber: string): Promise<CarrierResult>;
+export declare function fetchCainiao(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 export declare const adapter: AdapterFactory;

package/dist/carriers/aliexpress/adapter.js

@@ -1,7 +1,22 @@
+/**
+ * AliExpress / Cainiao tracking.
+ *
+ * Cainiao's public shipment detail endpoint (`global.cainiao.com/global/
+ * detail.json`) is the same keyless JSON the consumer tracking page reads. One
+ * GET returns every requested `mailNo` as a module, so the adapter selects the
+ * module whose identifier equals the number that was asked for and refuses
+ * anything else: the endpoint happily echoes other shipments when the query is
+ * malformed, and showing a stranger's parcel would be worse than an error.
+ *
+ * A module with no status, no history and no latest trace is genuinely unknown
+ * only when `mailNoSource` is `EXTERNAL`; otherwise Cainiao is still waiting
+ * for the seller and the parcel is simply pending.
+ */
+import { lookupBudget } from '../../core/adapter/index.js';
 import { normalizeTrackingNumber } from '../../core/detection/normalize.js';
 import { NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { explicitOffsetTime } from '../../core/time/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 { CAINIAO_ACTION_STATUS, CAINIAO_STATUS, cainiaoActionCode, cainiaoStageByStatus, } from './status.js';
 const PROVIDER = 'Cainiao';
@@ -12,7 +27,6 @@ const MAX_EVENTS_TO_RETURN = 20;
 const BASE_HEADERS = {
     Accept: 'application/json, text/plain, */*',
     'Accept-Language': 'en-US,en;q=0.9',
-    'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
 };
 function record(value) {
     return isRecord(value) ? value : {};
@@ -140,25 +154,31 @@ export function parseCainiaoTrackingResponse(value, trackingNumber) {
 export class CainiaoTracker {
     fetcher;
     timeoutMs;
+    userAgent;
     constructor(options = {}) {
         this.fetcher = options.fetcher;
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.userAgent = userAgentOf(options.userAgent);
     }
-    async fetch(trackingNumber) {
-        const { bytes } = await fetchBounded(`${DETAIL_URL}?${new URLSearchParams({ mailNos: trackingNumber, lang: 'en-US' })}`, { headers: { ...BASE_HEADERS, Referer: 'https://www.aliexpress.com/' } }, { provider: UPSTREAM, timeoutMs: this.timeoutMs, fetcher: this.fetcher });
+    async fetch(trackingNumber, context = {}) {
+        const budget = lookupBudget(context, this.timeoutMs);
+        const { bytes } = await fetchBounded(`${DETAIL_URL}?${new URLSearchParams({ mailNos: trackingNumber, lang: 'en-US' })}`, {
+            signal: budget.signal,
+            headers: { ...BASE_HEADERS, 'User-Agent': this.userAgent, Referer: 'https://www.aliexpress.com/' },
+        }, { provider: UPSTREAM, timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()), fetcher: this.fetcher });
         return parseCainiaoTrackingResponse(parseJsonBytes(bytes, UPSTREAM), trackingNumber);
     }
 }
 /** Kept for the host's legacy dispatch chain until it is deleted. */
-export async function fetchCainiao(trackingNumber) {
-    return new CainiaoTracker().fetch(trackingNumber);
+export async function fetchCainiao(trackingNumber, context = {}) {
+    return new CainiaoTracker().fetch(trackingNumber, context);
 }
 export const adapter = (environment) => {
-    const tracker = new CainiaoTracker({ fetcher: environment.fetcher });
+    const tracker = new CainiaoTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'aliexpress',
         // One keyless GET; there is no second tier to fall back to.
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/amazon-shipping/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 { IndeterminateError, NotFoundError } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 export { amazonShippingStatus } from './status.js';
@@ -6,6 +6,7 @@ export interface AmazonShippingOptions {
     timeoutMs?: number;
     /** Test seam; production uses the global fetch. */
     fetcher?: typeof fetch;
+    userAgent?: string;
 }
 /** A confirmed absence, with a public reason consumers can inspect. */
 export declare class AmazonShippingNotFoundError extends NotFoundError {
@@ -29,6 +30,6 @@ export declare class AmazonShippingTracker {
     #private;
     readonly timeoutMs: number;
     constructor(options?: number | AmazonShippingOptions);
-    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/amazon-shipping/adapter.js

@@ -1,8 +1,9 @@
 import { DateTime } from 'luxon';
+import { lookupBudget } from '../../core/adapter/index.js';
 import { amazonShippingOrigin, amazonShippingUrl } from '../../core/catalog/index.js';
 import { isAmazonTrackingNumber } from '../../core/detection/index.js';
-import { IndeterminateError, InputRequiredError, NotFoundError, SchemaError } from '../../core/errors/index.js';
-import { cleanScalar, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { cleanScalar, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyStatus, statusKey } from './status.js';
 const PROVIDER = 'Amazon Shipping';
@@ -155,7 +156,7 @@ function metadataValue(metadata, field) {
 export function normalizeAmazonShippingTrackingNumber(raw) {
     const value = raw.trim().toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
     if (!isAmazonTrackingNumber(value)) {
-        throw new InputRequiredError(PROVIDER, 'a European country prefix and 10 digits, or TBA and 12 digits', 'Amazon tracking numbers need a European country prefix and 10 digits, or TBA and 12 digits');
+        throw new InvalidInputError(PROVIDER, 'Amazon tracking numbers need a European country prefix and 10 digits, or TBA and 12 digits');
     }
     return value;
 }
@@ -254,28 +255,32 @@ export function amazonShippingTimezone(number) {
 export class AmazonShippingTracker {
     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('Amazon Shipping timeout must be positive');
         }
         this.timeoutMs = timeoutMs;
         this.#fetcher = fetcher;
+        this.#userAgent = userAgentOf(userAgent);
     }
-    async fetch(rawTrackingNumber) {
+    async fetch(rawTrackingNumber, context = {}) {
         const trackingNumber = normalizeAmazonShippingTrackingNumber(rawTrackingNumber);
+        const budget = lookupBudget(context, this.timeoutMs);
         const { bytes } = await fetchBounded(amazonShippingTrackingApiUrl(trackingNumber), {
+            signal: budget.signal,
             headers: {
                 Accept: 'application/json',
                 'Accept-Language': 'en-US,en;q=0.9',
                 Referer: amazonShippingTrackingUrl(trackingNumber),
-                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+                'User-Agent': this.#userAgent,
             },
         }, {
             provider: 'Amazon Shipping tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
         });
@@ -283,10 +288,10 @@ export class AmazonShippingTracker {
     }
 }
 export const adapter = (environment) => {
-    const tracker = new AmazonShippingTracker({ fetcher: environment.fetcher });
+    const tracker = new AmazonShippingTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'amazon-shipping',
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/amazon-shipping/eligibility.d.ts

@@ -1,3 +1,4 @@
 import { type AmazonShippingOptions } from './adapter.js';
+import type { TrackingContext } from '../../core/adapter/index.js';
 /** A public eligibility check; transport errors remain errors for the consumer to report. */
-export declare function amazonShippingEligibility(number: string, options?: AmazonShippingOptions): Promise<'available' | 'expired' | 'not-found'>;
+export declare function amazonShippingEligibility(number: string, options?: AmazonShippingOptions, context?: TrackingContext): Promise<'available' | 'expired' | 'not-found'>;

package/dist/carriers/amazon-shipping/eligibility.js

@@ -1,9 +1,9 @@
 import { AmazonShippingTracker } from './adapter.js';
 import { CarrierError } from '../../core/errors/index.js';
 /** A public eligibility check; transport errors remain errors for the consumer to report. */
-export async function amazonShippingEligibility(number, options = {}) {
+export async function amazonShippingEligibility(number, options = {}, context = {}) {
     try {
-        await new AmazonShippingTracker({ ...options, timeoutMs: options.timeoutMs ?? 5_000 }).fetch(number);
+        await new AmazonShippingTracker({ ...options, timeoutMs: options.timeoutMs ?? 5_000 }).fetch(number, context);
         return 'available';
     }
     catch (error) {

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

@@ -2,9 +2,11 @@ import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.j
 import { type StepRecorder } from '../../core/telemetry/index.js';
 export declare class AramexTracker {
     private readonly options;
+    private readonly userAgent;
     constructor(options?: {
         fetcher?: typeof fetch;
         recorder?: StepRecorder;
+        userAgent?: string;
     });
     fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
 }

package/dist/carriers/aramex/adapter.js

@@ -1,12 +1,14 @@
 import { BudgetExceededError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
-import { decodeText, fetchBounded } from '../../core/transport/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
 import { aramexDetailRedirect, aramexDetailUrl, normalizeAramexNumber, parseAramex } from './parser.js';
 export class AramexTracker {
     options;
+    userAgent;
     constructor(options = {}) {
         this.options = options;
+        this.userAgent = userAgentOf(options.userAgent);
     }
     fetch(raw, context = {}) {
         const number = normalizeAramexNumber(raw);
@@ -21,7 +23,7 @@ export class AramexTracker {
                         try {
                             // The edge rejects Node's default user agent on server networks.
                             const { response, bytes } = await fetchBounded(url, { signal, headers: {
-                                    Accept: 'text/html', 'User-Agent': 'SwissDeliveryTracker/1.0',
+                                    Accept: 'text/html', 'User-Agent': this.userAgent,
                                 } }, {
                                 provider: 'Aramex', timeoutMs: Math.max(1, Math.floor(left)), maxBytes: 1_500_000,
                                 fetcher: this.options.fetcher, ...(regionalRedirect ? { redirect: 'manual', allowHttpStatuses: [301, 302, 303, 307, 308] } : {}),
@@ -44,6 +46,6 @@ export class AramexTracker {
     }
 }
 export const adapter = environment => {
-    const tracker = new AramexTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    const tracker = new AramexTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
     return { id: 'aramex', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
 };

package/dist/carriers/aramex/parser.js

@@ -1,12 +1,12 @@
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
-import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { clean } from '../../core/transport/index.js';
 import { classifyAramexStatus } from './status.js';
 export function normalizeAramexNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!/^\d{11,12}$/.test(number))
-        throw new TypeError('Aramex requires an eleven- or twelve-digit shipment number');
+        throw new InvalidInputError('Aramex', 'Aramex requires an eleven- or twelve-digit shipment number');
     return number;
 }
 export function aramexDetailUrl(html, number) {

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

@@ -61,11 +61,13 @@ export interface AsendiaA1TrackerOptions {
     /** Wall clock in milliseconds, for the configuration cache and budgets. */
     now?: () => number;
     budgetMs?: number;
+    userAgent?: string;
 }
 export declare class AsendiaA1Tracker {
     private readonly fetcher?;
     private readonly now;
     private readonly budgetMs;
+    private readonly userAgent;
     private cached;
     private loading;
     constructor(options?: AsendiaA1TrackerOptions);
@@ -73,10 +75,16 @@ export declare class AsendiaA1Tracker {
     private freshConfig;
     /** One page read at a time; concurrent lookups share it. */
     private loadConfig;
+    private startRead;
+    /** Waits for a read another lookup started, no longer than this lookup's own signal and budget allow. */
+    private whileLive;
+    /** Whether a failed read was ended by its own lookup's cancellation or budget rather than by Asendia. */
+    private cutShort;
     private readConfig;
     private keyAccepted;
     private tracking;
     private api;
     private requestTimeout;
+    private remaining;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/asendia/adapter.js

@@ -1,18 +1,19 @@
 import { carrierIdFromPartner } from '../../core/catalog/hints.js';
-import { BudgetExceededError, ChallengeError, IndeterminateError, NotFoundError, SchemaError, UpstreamHttpError, } from '../../core/errors/index.js';
+import { BudgetExceededError, ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
 import { languageStageStatus, wordingStage } from '../../core/status/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
-import { clean, cleanScalar, decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { clean, cleanScalar, decodeText, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyAsendiaA1Event } from './status.js';
 const PROVIDER = 'Asendia';
 const PAGE_URL = 'https://a1.asendiausa.com/tracking/';
 const SCRIPT_URL = `${PAGE_URL}js/main.js`;
 const API_HOST_SUFFIXES = ['asendiaprod.com', 'asendia.io', 'asendia.com', 'asendiausa.com'];
-const USER_AGENT = 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)';
 const GUID = /[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}/gi;
 const DEFAULT_BUDGET_MS = 25_000;
 const MAX_REQUEST_MS = 10_000;
+/** The longest delay a timer holds; a longer one fires at once. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
 /** The public configuration is re-read at least this often, in case it rotates. */
 const CONFIG_TTL_MS = 6 * 60 * 60_000;
 /** A not-found is only trusted when the tracking key was accepted this recently. */
@@ -39,7 +40,7 @@ function comparable(value) {
 export function normalizeAsendiaA1TrackingNumber(raw) {
     const value = comparable(raw);
     if (!/^[A-Z0-9]{6,40}$/.test(value)) {
-        throw new TypeError('Asendia tracking numbers must contain 6 to 40 ASCII letters and digits');
+        throw new InvalidInputError(PROVIDER, 'Asendia tracking numbers must contain 6 to 40 ASCII letters and digits');
     }
     return value;
 }
@@ -206,6 +207,7 @@ export class AsendiaA1Tracker {
     fetcher;
     now;
     budgetMs;
+    userAgent;
     cached = null;
     loading = null;
     constructor(options = {}) {
@@ -214,6 +216,7 @@ export class AsendiaA1Tracker {
         this.budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
         if (!Number.isFinite(this.budgetMs) || this.budgetMs <= 0)
             throw new TypeError('Asendia budget must be positive');
+        this.userAgent = userAgentOf(options.userAgent);
     }
     async fetch(rawTrackingNumber, context = {}) {
         const trackingNumber = normalizeAsendiaA1TrackingNumber(rawTrackingNumber);
@@ -256,13 +259,59 @@ export class AsendiaA1Tracker {
         return this.cached && this.now() - this.cached.loadedAt < CONFIG_TTL_MS ? this.cached : null;
     }
     /** One page read at a time; concurrent lookups share it. */
-    loadConfig(request) {
-        this.loading ??= this.readConfig(request).finally(() => { this.loading = null; });
-        return this.loading;
+    async loadConfig(request) {
+        for (;;) {
+            const read = this.loading ??= this.startRead(request);
+            if (read.owner === request)
+                return read.promise;
+            const outcome = await this.whileLive(read.promise.then((config) => ({ config }), (error) => ({ error })), request);
+            if ('config' in outcome)
+                return outcome.config;
+            // A read cut short by its own lookup's cancellation or budget says
+            // nothing about Asendia: a lookup that shared it reads again.
+            if (!read.cut)
+                throw outcome.error;
+        }
+    }
+    startRead(owner) {
+        const read = {
+            owner,
+            cut: false,
+            promise: this.readConfig(owner).catch((error) => {
+                // Judged as the read fails: a host may cancel the lookup once it has settled.
+                read.cut = this.cutShort(owner, error);
+                throw error;
+            }).finally(() => { this.loading = null; }),
+        };
+        return read;
+    }
+    /** Waits for a read another lookup started, no longer than this lookup's own signal and budget allow. */
+    async whileLive(shared, request) {
+        let leave;
+        const gone = new Promise((_resolve, reject) => { leave = reject; });
+        const cancelled = () => leave(request.signal?.reason);
+        const spent = setTimeout(() => leave(new BudgetExceededError(PROVIDER, request.budgetMs)), Math.min(MAX_TIMER_MS, this.remaining(request)));
+        request.signal?.addEventListener('abort', cancelled, { once: true });
+        try {
+            return await Promise.race([shared, gone]);
+        }
+        finally {
+            clearTimeout(spent);
+            request.signal?.removeEventListener('abort', cancelled);
+        }
+    }
+    /** Whether a failed read was ended by its own lookup's cancellation or budget rather than by Asendia. */
+    cutShort(owner, error) {
+        if (owner.signal?.aborted || owner.deadline - this.now() < 1)
+            return true;
+        // A request timer can fire just before the clock reaches the deadline.
+        return owner.budgetBound === true && error instanceof UpstreamNetworkError
+            && isRecord(error.cause) && error.cause.name === 'TimeoutError';
     }
     async readConfig(request) {
         const { bytes } = await fetchBounded(SCRIPT_URL, {
-            headers: { Accept: '*/*', Referer: PAGE_URL, 'User-Agent': USER_AGENT },
+            signal: request.signal,
+            headers: { Accept: '*/*', Referer: PAGE_URL, 'User-Agent': this.userAgent },
         }, {
             provider: 'Asendia tracking page', timeoutMs: this.requestTimeout(request), maxBytes: MAX_SCRIPT_BYTES, fetcher: this.fetcher,
         });
@@ -293,11 +342,12 @@ export class AsendiaA1Tracker {
     }
     async api(url, config, request, provider) {
         const { response, bytes } = await fetchBounded(url, {
+            signal: request.signal,
             headers: {
                 Accept: 'application/json',
                 Authorization: config.authorization,
                 'X-AsendiaOne-ApiKey': config.apiKey,
-                'User-Agent': USER_AGENT,
+                'User-Agent': this.userAgent,
             },
         }, {
             provider, timeoutMs: this.requestTimeout(request), maxBytes: MAX_RESPONSE_BYTES, fetcher: this.fetcher,
@@ -324,15 +374,20 @@ export class AsendiaA1Tracker {
         return payload;
     }
     requestTimeout(request) {
+        const remaining = this.remaining(request);
+        request.budgetBound = remaining <= MAX_REQUEST_MS;
+        return Math.min(MAX_REQUEST_MS, remaining);
+    }
+    remaining(request) {
         request.signal?.throwIfAborted();
         const remaining = Math.floor(request.deadline - this.now());
         if (remaining < 1)
             throw new BudgetExceededError(PROVIDER, request.budgetMs);
-        return Math.min(MAX_REQUEST_MS, remaining);
+        return remaining;
     }
 }
 export const adapter = (environment) => {
-    const tracker = new AsendiaA1Tracker({ fetcher: environment.fetcher });
+    const tracker = new AsendiaA1Tracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'asendia',
         // Plain HTTP against the public page's own API; no second tier.

package/dist/carriers/asendia/probe.d.ts

@@ -18,12 +18,14 @@ export interface AsendiaTrackerOptions {
     turnstileTokenProvider?: () => string | Promise<string>;
     /** Test seam; production uses the global fetch. */
     fetcher?: typeof fetch;
+    userAgent?: string;
 }
 export declare class AsendiaTracker {
     readonly timeoutMs: number;
     readonly now: () => Date;
     readonly turnstileTokenProvider: () => string | Promise<string>;
     readonly fetcher?: typeof fetch;
+    readonly userAgent: string;
     constructor(options?: AsendiaTrackerOptions);
     fetch(rawTrackingNumber: string): Promise<CarrierResult>;
     private requestText;

package/dist/carriers/asendia/probe.js

@@ -24,9 +24,9 @@
 import { createHash } from 'node:crypto';
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
-import { ChallengeError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { ChallengeError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { isoTime, zonedTime } from '../../core/time/index.js';
-import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, userAgentOf, } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyAsendiaStatus } from './status.js';
 const TRACKING_ORIGIN = 'https://track.asendia.com';
@@ -59,7 +59,7 @@ function plainText(value, maxLength = 500) {
 export function normalizeAsendiaTrackingNumber(raw) {
     const value = raw.toLocaleUpperCase('en-US').replace(/[\s-]/g, '');
     if (!/^[A-Z0-9]{8,40}$/.test(value) || !/\d/.test(value)) {
-        throw new TypeError('Asendia tracking numbers must contain 8 to 40 ASCII letters and digits');
+        throw new InvalidInputError('Asendia', 'Asendia tracking numbers must contain 8 to 40 ASCII letters and digits');
     }
     return value;
 }
@@ -260,7 +260,7 @@ function challengeToken(value) {
     }
     return token;
 }
-function baseHeaders() {
+function baseHeaders(userAgent) {
     return {
         Accept: 'application/json',
         'Accept-Language': 'en',
@@ -270,7 +270,7 @@ function baseHeaders() {
         'X-Timezone': ZONE,
         Origin: TRACKING_ORIGIN,
         Referer: `${TRACKING_PAGE}/`,
-        'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+        'User-Agent': userAgent,
     };
 }
 export class AsendiaTracker {
@@ -278,6 +278,7 @@ export class AsendiaTracker {
     now;
     turnstileTokenProvider;
     fetcher;
+    userAgent;
     constructor(options = {}) {
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.now = options.now ?? (() => new Date());
@@ -287,13 +288,14 @@ export class AsendiaTracker {
         if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
             throw new TypeError('Asendia timeout must be positive');
         }
+        this.userAgent = userAgentOf(options.userAgent);
     }
     async fetch(rawTrackingNumber) {
         const trackingNumber = normalizeAsendiaTrackingNumber(rawTrackingNumber);
         const token = challengeToken(await this.turnstileTokenProvider());
         const [environmentScript, configPayload] = await Promise.all([
             this.requestText(ENVIRONMENT_SCRIPT, 'Asendia public environment'),
-            this.requestJson(CONFIG_API, { headers: baseHeaders() }, 'Asendia tracking configuration'),
+            this.requestJson(CONFIG_API, { headers: baseHeaders(this.userAgent) }, 'Asendia tracking configuration'),
         ]);
         const publicHitKey = parseAsendiaPublicHitKey(environmentScript);
         const config = parseTenantConfig(configPayload);
@@ -301,7 +303,7 @@ export class AsendiaTracker {
         const hitToken = asendiaHitToken(trackingNumber, date, publicHitKey);
         const payload = await this.requestJson(asendiaTrackingApiUrl(), {
             method: 'POST',
-            headers: { ...baseHeaders(), 'X-Hit-Token': hitToken },
+            headers: { ...baseHeaders(this.userAgent), 'X-Hit-Token': hitToken },
             body: JSON.stringify({
                 ids: [trackingNumber],
                 id: config.id,

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

@@ -1,4 +1,4 @@
-import { BudgetExceededError, ChallengeError, InputRequiredError, NotFoundError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { BudgetExceededError, ChallengeError, InvalidInputError, NotFoundError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { explicitOffsetTime, epochMillisTime } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
@@ -12,7 +12,7 @@ const TRANSPORT_ALLOWANCE_MS = 15_000;
 export function normalizeAustraliaPostNumber(raw) {
     const number = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^(?=.*\d)[A-Z0-9]{10,34}$/.test(number)) {
-        throw new InputRequiredError(PROVIDER, 'number', 'Australia Post requires a 10-to-34-character tracking number');
+        throw new InvalidInputError(PROVIDER, 'Australia Post requires a 10-to-34-character tracking number');
     }
     return number;
 }

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

@@ -1,6 +1,6 @@
 import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
-import { IndeterminateError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
 import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
@@ -12,7 +12,7 @@ const ENDPOINT = 'https://api.post.at/sendungen/sv/graphqlPublic';
 export function normalizeAustrianPostNumber(raw) {
     const number = normalizeTrackingNumber(raw);
     if (!/^\d{22}$/.test(number) && !(/^[A-Z]{2}\d{9}AT$/.test(number) && isValidS10TrackingNumber(number))) {
-        throw new TypeError('Austrian Post requires a 22-digit or valid AT postal identifier');
+        throw new InvalidInputError(PROVIDER, 'Austrian Post requires a 22-digit or valid AT postal identifier');
     }
     return number;
 }

package/dist/carriers/blue-dart/parser.js

@@ -1,12 +1,12 @@
 import { load } from 'cheerio';
-import { IndeterminateError, 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 } from '../../core/transport/index.js';
 import { classifyBlueDartStatus } from './status.js';
 export function normalizeBlueDartNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!/^\d{11}$/.test(number))
-        throw new TypeError('Blue Dart requires an eleven-digit waybill');
+        throw new InvalidInputError('Blue Dart', 'Blue Dart requires an eleven-digit waybill');
     return number;
 }
 export function parseBlueDart(html, number) {

package/dist/carriers/bpost/parser.js

@@ -1,13 +1,13 @@
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
-import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { clean } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyBpostStatus } from './status.js';
 export function normalizeBpostNumber(raw) {
     const number = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^(?:\d{18}|\d{24}|\d{30})$/.test(number) && !isValidS10TrackingNumber(number)) {
-        throw new TypeError('bpost requires a parcel barcode or postal tracking number');
+        throw new InvalidInputError('bpost', 'bpost requires a parcel barcode or postal tracking number');
     }
     return number;
 }

package/dist/carriers/bring-posten/parser.js

@@ -1,6 +1,6 @@
 import { DateTime } from 'luxon';
 import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
-import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
@@ -8,7 +8,7 @@ import { bringStatus, bringWording } from './status.js';
 export function normalizeBringNumber(raw) {
     const number = normalizeTrackingNumber(raw);
     if (!/^\d{17,18}$/.test(number) && !(/^[A-Z]{2}\d{9}NO$/.test(number) && isValidS10TrackingNumber(number))) {
-        throw new TypeError('Bring requires a parcel or consignment tracking number');
+        throw new InvalidInputError('Bring', 'Bring requires a parcel or consignment tracking number');
     }
     return number;
 }

package/dist/carriers/brt/parser.js

@@ -1,12 +1,12 @@
 import { load } from 'cheerio';
-import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { calendarDay } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
 import { classifyBrtStatus } from './status.js';
 export function normalizeBrtNumber(raw) {
     const number = raw.replace(/\s/g, '');
     if (!/^\d{14}$/.test(number))
-        throw new TypeError('BRT requires a fourteen-digit BRTcode');
+        throw new InvalidInputError('BRT', 'BRT requires a fourteen-digit BRTcode');
     return number;
 }
 function scanClock(date, clock) {