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

package/dist/carriers/ctt/adapter.js

@@ -1,4 +1,5 @@
-import { IndeterminateError, MaintenanceError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+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';
@@ -54,7 +55,7 @@ export function normalizeCttTrackingNumber(raw) {
     // the generic postal fallback — those routes were never sampled here.
     const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
     if (!/^[A-Z]{2}\d{9}PT$/.test(value) || !isValidS10TrackingNumber(value)) {
-        throw new TypeError('CTT tracking requires a valid 13-character S10 number ending in PT');
+        throw new InvalidInputError('CTT', 'CTT tracking requires a valid 13-character S10 number ending in PT');
     }
     return value;
 }
@@ -167,31 +168,32 @@ export class CttTracker {
             throw new TypeError('CTT timeout must be positive');
         }
     }
-    async fetch(rawTrackingNumber) {
+    async fetch(rawTrackingNumber, context = {}) {
         const trackingNumber = normalizeCttTrackingNumber(rawTrackingNumber);
+        const budget = lookupBudget(context, this.timeoutMs);
         const payload = await this.callAction(TRACK_ACTION, {
             ObjectCodeInput: trackingNumber,
             SearchInput: trackingNumber,
             IsFromPublicArea: true,
             IPClient: '',
-        }, null, true, true);
+        }, null, true, true, budget);
         const record = isRecord(payload.data) ? payload.data.ObjectEventsFromQuery : undefined;
         if (!isRecord(record) || !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())
+            if (await this.isMaintenance(budget))
                 throw new CttMaintenanceError();
             throw new NotFoundError('CTT');
         }
         return parseCttTrackingResponse(payload, trackingNumber);
     }
-    async isMaintenance() {
-        const payload = await this.callAction(MAINTENANCE_ACTION, {}, null, true, true);
+    async isMaintenance(budget) {
+        const payload = await this.callAction(MAINTENANCE_ACTION, {}, null, true, true, budget);
         const data = isRecord(payload.data) ? payload.data : {};
         return data.IsMaintenance === true;
     }
-    async callAction(action, variables, session, retrySession, retryVersion) {
-        const apiVersion = await this.ensureApiVersion(action);
+    async callAction(action, variables, session, retrySession, retryVersion, budget) {
+        const apiVersion = await this.ensureApiVersion(action, budget);
         const headers = {
             Accept: 'application/json',
             'Content-Type': 'application/json; charset=UTF-8',
@@ -203,6 +205,7 @@ export class CttTracker {
         }
         const { response, bytes } = await fetchBounded(`${BASE_URL}${SCREEN_PATH}/${action}`, {
             method: 'POST',
+            signal: budget.signal,
             headers,
             body: JSON.stringify({
                 versionInfo: { moduleVersion: this.moduleVersion, apiVersion },
@@ -211,7 +214,7 @@ export class CttTracker {
             }),
         }, {
             provider: 'CTT tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
             allowHttpError: true,
@@ -220,7 +223,7 @@ export class CttTracker {
         if (response.status === 403) {
             const bootstrapped = sessionFromSetCookie(response);
             if (retrySession && bootstrapped) {
-                return this.callAction(action, variables, bootstrapped, false, retryVersion);
+                return this.callAction(action, variables, bootstrapped, false, retryVersion, budget);
             }
             throw new CttApiError('anonymous session bootstrap failed');
         }
@@ -234,30 +237,31 @@ export class CttTracker {
             this.moduleVersion = null;
             this.screenScript = null;
             this.apiVersions.delete(action);
-            return this.callAction(action, variables, session, retrySession, false);
+            return this.callAction(action, variables, session, retrySession, false, budget);
         }
         return payload;
     }
-    async ensureApiVersion(action) {
+    async ensureApiVersion(action, budget) {
         const cached = this.apiVersions.get(action);
         if (cached !== undefined)
             return cached;
-        await this.ensureModuleVersion();
-        const script = await this.ensureScreenScript();
+        await this.ensureModuleVersion(budget);
+        const script = await this.ensureScreenScript(budget);
         const version = new RegExp(`callDataAction\\("${escapeRegExp(action)}",\\s*"[^"]*",\\s*"([^"]+)"`).exec(script)?.[1];
         if (!version)
             throw new CttApiError(`could not derive apiVersion for ${action}`);
         this.apiVersions.set(action, version);
         return version;
     }
-    async ensureModuleVersion() {
+    async ensureModuleVersion(budget) {
         if (this.moduleVersion !== null)
             return;
         const { response, bytes } = await fetchBounded(MODULE_VERSION_URL, {
+            signal: budget.signal,
             headers: { Accept: 'application/json', 'User-Agent': BROWSER_USER_AGENT },
         }, {
             provider: 'CTT tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_RESPONSE_BYTES,
             retryTransient: true,
             allowHttpError: true,
@@ -271,13 +275,13 @@ export class CttTracker {
             throw new CttApiError('moduleversioninfo returned no versionToken');
         this.moduleVersion = token;
     }
-    async ensureScreenScript() {
+    async ensureScreenScript(budget) {
         if (this.screenScript !== null)
             return this.screenScript;
         // The version token carries +/= characters: it must travel percent-encoded
         // or the manifest endpoint answers an unrelated shape.
         const manifestUrl = `${BASE_URL}/CustomerArea/moduleservices/moduleinfo?${encodeURIComponent(this.moduleVersion ?? '')}`;
-        const manifest = await this.fetchJson(manifestUrl);
+        const manifest = await this.fetchJson(manifestUrl, budget);
         const versions = isRecord(manifest) && isRecord(manifest.manifest) && isRecord(manifest.manifest.urlVersions)
             ? manifest.manifest.urlVersions
             : {};
@@ -285,19 +289,20 @@ export class CttTracker {
         if (typeof scriptToken !== 'string' || !scriptToken) {
             throw new CttApiError("module manifest missing the screen script's version token");
         }
-        const script = decodeText((await this.fetchBytes(`${BASE_URL}${SCREEN_SCRIPT_PATH}?${scriptToken}`)).bytes);
+        const script = decodeText((await this.fetchBytes(`${BASE_URL}${SCREEN_SCRIPT_PATH}?${scriptToken}`, budget)).bytes);
         this.screenScript = script;
         return script;
     }
-    async fetchJson(url) {
-        return parseJsonBytes((await this.fetchBytes(url)).bytes, 'CTT tracking');
+    async fetchJson(url, budget) {
+        return parseJsonBytes((await this.fetchBytes(url, budget)).bytes, 'CTT tracking');
     }
-    async fetchBytes(url) {
+    async fetchBytes(url, budget) {
         const { response, bytes } = await fetchBounded(url, {
+            signal: budget.signal,
             headers: { Accept: 'application/json, text/plain, */*', 'User-Agent': BROWSER_USER_AGENT },
         }, {
             provider: 'CTT tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             maxBytes: MAX_SCRIPT_BYTES,
             retryTransient: true,
             allowHttpError: true,
@@ -315,6 +320,6 @@ export const adapter = (environment) => {
         // The OutSystems session bootstrap and the version-token refresh are part
         // of the direct call, not separate tiers: they never change the transport.
         steps: ['direct'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/ctt-express/parser.js

@@ -1,5 +1,5 @@
 import { DateTime } from 'luxon';
-import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
 import { calendarDay, explicitOffsetTime } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
@@ -7,7 +7,7 @@ import { classifyCttExpressStatus } from './status.js';
 export function normalizeCttExpressNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!/^00\d{20}$/.test(number))
-        throw new TypeError('CTT Express requires a Spanish shipment tracking number');
+        throw new InvalidInputError('CTT Express', 'CTT Express requires a Spanish shipment tracking number');
     return number;
 }
 function scanClock(value) {

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

@@ -1,10 +1,11 @@
 export { validateDachserTrackingUrl } from '../../core/catalog/urls.js';
-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 interface DachserOptions {
     timeoutMs?: number;
     /** Test seam; production uses the global fetch. */
     fetcher?: typeof fetch;
+    userAgent?: string;
 }
 /**
  * Validate and canonicalize a pasted Dachser capability URL.
@@ -20,6 +21,6 @@ export declare class DachserTracker {
     #private;
     readonly timeoutMs: number;
     constructor(options?: number | DachserOptions);
-    fetch(trackingNumber: string, trackingUrl: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, trackingUrl: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/dachser/adapter.js

@@ -1,8 +1,9 @@
 import { validateDachserTrackingUrl } from '../../core/catalog/urls.js';
 export { validateDachserTrackingUrl } from '../../core/catalog/urls.js';
 import { DateTime } from 'luxon';
-import { InputRequiredError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
-import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { lookupBudget } from '../../core/adapter/index.js';
+import { InputRequiredError, InvalidInputError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { eventLabel, plainText, shipmentStatus } from './status.js';
 const DACHSER_HOST = 'customeriberia.dachser.com';
@@ -30,7 +31,17 @@ function normalizeTrackingNumber(raw) {
  * like a password.
  */
 export function dachserApiUrl(trackingUrl, trackingNumber) {
-    const url = new URL(validateDachserTrackingUrl(trackingUrl, trackingNumber));
+    let validated;
+    try {
+        validated = validateDachserTrackingUrl(trackingUrl, trackingNumber);
+    }
+    catch (error) {
+        // A link that is not this shipment's is the caller's credential, rejected before any request.
+        if (error instanceof TypeError)
+            throw new InvalidInputError(PROVIDER, error.message, { cause: error });
+        throw error;
+    }
+    const url = new URL(validated);
     url.pathname = DACHSER_API_PATH;
     return url.toString();
 }
@@ -105,24 +116,29 @@ export function parseDachserTrackingResponse(payload, trackingNumber) {
 export class DachserTracker {
     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, trackingUrl) {
-        const { bytes, response } = await fetchBounded(dachserApiUrl(trackingUrl, trackingNumber), {
+    async fetch(trackingNumber, trackingUrl, context = {}) {
+        const url = dachserApiUrl(trackingUrl, trackingNumber);
+        const budget = lookupBudget(context, this.timeoutMs);
+        const { bytes, response } = await fetchBounded(url, {
+            signal: budget.signal,
             headers: {
                 Accept: 'application/json',
                 'Accept-Language': 'en',
                 Referer: `https://${DACHSER_HOST}${DACHSER_PAGE_PATH}`,
-                'User-Agent': 'SwissDeliveryTracker/1.0',
+                'User-Agent': this.#userAgent,
             },
         }, {
             provider: 'Dachser tracking',
-            timeoutMs: this.timeoutMs,
+            timeoutMs: Math.min(this.timeoutMs, budget.remainingMs()),
             allowHttpError: true,
             ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
         });
@@ -136,10 +152,12 @@ export class DachserTracker {
             catch {
                 throw new UpstreamHttpError('Dachser tracking', response.status);
             }
-            // An unknown shipment/access tuple currently reaches a null result in
-            // Dachser's public endpoint and is surfaced as this stable JSON 500.
-            // Match the public error signature narrowly so unrelated 500s remain
-            // operational failures rather than false not-found results.
+            // An unknown shipment/access tuple reaches a null result in Dachser's
+            // public endpoint and surfaces as a JSON 500 whose message names it.
+            // ERR_APP_500 is the endpoint's catch-all for any unhandled exception and
+            // the message is the only field that says which one, so the `message: null`
+            // reply the same tuple also gets stays an operational failure, like every
+            // unrelated 500, rather than a false not-found.
             const errorMessage = plainText(isRecord(errorPayload) ? errorPayload.message ?? '' : '');
             if (response.status === 500
                 && isRecord(errorPayload)
@@ -154,15 +172,15 @@ export class DachserTracker {
     }
 }
 export const adapter = (environment) => {
-    const tracker = new DachserTracker({ fetcher: environment.fetcher });
+    const tracker = new DachserTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'dachser',
         steps: ['direct'],
-        track: async (input) => {
+        track: async (input, context) => {
             if (!input.trackingUrl) {
                 throw new InputRequiredError(PROVIDER, 'its complete tracking URL', 'Dachser tracking requires its complete tracking URL');
             }
-            return tracker.fetch(input.number, input.trackingUrl);
+            return tracker.fetch(input.number, input.trackingUrl, context);
         },
     };
 };

package/dist/carriers/delhivery/parser.js

@@ -1,4 +1,4 @@
-import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { isoTime } from '../../core/time/index.js';
 import { clean } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
@@ -13,7 +13,7 @@ function scanTime(value) {
 export function normalizeDelhiveryNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!/^\d{13,14}$/.test(number))
-        throw new TypeError('Delhivery requires a thirteen- or fourteen-digit waybill');
+        throw new InvalidInputError('Delhivery', 'Delhivery requires a thirteen- or fourteen-digit waybill');
     return number;
 }
 export function parseDelhivery(payload, number) {

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

@@ -13,7 +13,7 @@
  *
  * DHL's business API credentials are not needed for this public flow.
  */
-import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
 import { ChallengeError, type CarrierErrorOptions } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
@@ -60,7 +60,7 @@ export declare class DHLTracker {
     constructor(options?: DHLTrackerOptions);
     private open;
     /** Lookups share one session, so two parcels never renew it at the same time. */
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
     private lookup;
     /** The direct session, renewing a stale one or an interrupted read once. */
     private direct;

package/dist/carriers/dhl/adapter.js

@@ -15,9 +15,9 @@
  */
 import makeFetchCookie from 'fetch-cookie';
 import { Cookie, CookieJar } from 'tough-cookie';
-import { ChallengeError, IndeterminateError, InputRequiredError, RateLimitedError, SchemaError, } from '../../core/errors/index.js';
+import { ChallengeError, IndeterminateError, InputRequiredError, InvalidInputError, RateLimitedError, SchemaError, } from '../../core/errors/index.js';
 import { carrierIdFromPartnerLinks } from '../../core/catalog/hints.js';
-import { runSteps, singleFlight } from '../../core/runner/index.js';
+import { runSteps, singleFlight, takeTurn } from '../../core/runner/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { isoTime } from '../../core/time/index.js';
 import { clean as cleanText, fetchBounded, parseJsonBytes, TrawlClient, UpstreamHttpError, UpstreamNetworkError, } from '../../core/transport/index.js';
@@ -42,7 +42,7 @@ function clean(value, limit = 500) {
 export function normalizeDHLTrackingNumber(raw) {
     const value = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^[A-Z0-9]{5,40}$/.test(value))
-        throw new TypeError('DHL tracking number is invalid');
+        throw new InvalidInputError(PROVIDER, 'DHL tracking number is invalid');
     return value;
 }
 export function dhlTrackingUrl(number) {
@@ -152,6 +152,14 @@ const SESSION_MAX_AGE_MS = 100 * 60_000;
 function renewable(error) {
     return error instanceof DHLSessionError || error instanceof UpstreamNetworkError;
 }
+/** A request's own timeout, shortened to what is left of the lookup budget. */
+function capped(timeoutMs, { deadline }) {
+    return Math.max(1, Math.floor(Math.min(timeoutMs, deadline - performance.now())));
+}
+/** A lookup that was cancelled or ran out of time starts nothing more: no renewal, no browser. */
+function over(signal, deadline) {
+    return signal?.aborted === true || deadline - performance.now() < 1;
+}
 class DHLSession {
     timeoutMs;
     jar = new CookieJar();
@@ -182,9 +190,9 @@ class DHLSession {
             }), `https://${domain}${path}`);
         }
     }
-    async fetch(number) {
+    async fetch(number, limits) {
         if (!this.token) {
-            const config = await this.request(CONFIG_URL);
+            const config = await this.request(CONFIG_URL, limits);
             if (typeof config.verfolgenCsrfToken !== 'string' || !config.verfolgenCsrfToken)
                 throw new DHLSessionError();
             this.token = config.verfolgenCsrfToken;
@@ -192,16 +200,16 @@ class DHLSession {
         }
         const url = new URL(`${ORIGIN}${DATA_PATH}/search`);
         url.search = new URLSearchParams({ piececode: number, noRedirect: 'true', language: 'en' }).toString();
-        return parseDHLTrackingResponse(await this.request(url), number);
+        return parseDHLTrackingResponse(await this.request(url, limits), number);
     }
-    async request(url) {
-        const { response, bytes } = await fetchBounded(url, { headers: {
+    async request(url, limits) {
+        const { response, bytes } = await fetchBounded(url, { signal: limits.signal, headers: {
                 Accept: 'application/json, text/plain, */*', 'Accept-Language': 'en-US,en;q=0.9',
                 'User-Agent': this.userAgent, Referer: TRACKING_PAGE,
                 'Sec-Fetch-Site': 'same-origin', 'Sec-Fetch-Mode': 'cors', 'Sec-Fetch-Dest': 'empty',
                 ...(this.token ? { 'verfolgen-CSRF-token': this.token, 'verfolgen-wg': this.wg } : {}),
             } }, {
-            provider: PROVIDER, timeoutMs: this.timeoutMs, maxBytes: MAX_BYTES,
+            provider: PROVIDER, timeoutMs: capped(this.timeoutMs, limits), maxBytes: MAX_BYTES,
             fetcher: this.fetcher, redirect: 'manual', allowHttpError: true,
         });
         if ([301, 302, 303, 307, 308, 401, 403, 419].includes(response.status))
@@ -249,15 +257,32 @@ export class DHLTracker {
         return session;
     }
     /** Lookups share one session, so two parcels never renew it at the same time. */
-    async fetch(trackingNumber) {
+    async fetch(trackingNumber, context = {}) {
         const number = normalizeDHLTrackingNumber(trackingNumber);
-        return this.serialize(() => this.lookup(number));
+        return takeTurn(this.serialize, 'dhl', context, (left) => this.lookup(number, left));
     }
-    async lookup(number) {
+    async lookup(number, context) {
+        const { signal } = context;
+        // The caller may have left while the lookup waited for its turn.
+        signal?.throwIfAborted();
+        const budgetMs = context.budgetMs ?? this.budgetMs;
+        const deadline = performance.now() + budgetMs;
+        // The direct step's own signal: once it has aborted, the lookup is over and no browser follows.
+        let ended;
         try {
-            return await runSteps({ carrier: 'dhl', budgetMs: this.budgetMs, recorder: this.recorder }, [
-                { id: 'direct', run: () => this.direct(number) },
-                { id: 'trawl', enabled: this.trawl !== null || this.trawlUrl !== '', recovers: renewable, run: () => this.browser(number) },
+            return await runSteps({ carrier: 'dhl', budgetMs, signal, recorder: this.recorder }, [
+                {
+                    id: 'direct',
+                    run: (step) => {
+                        ended = step.signal;
+                        return this.direct(number, { signal: step.signal, deadline });
+                    },
+                },
+                {
+                    id: 'trawl', enabled: this.trawl !== null || this.trawlUrl !== '',
+                    recovers: (error) => renewable(error) && !over(ended, deadline),
+                    run: (step) => this.browser(number, { signal: step.signal, deadline }),
+                },
             ]);
         }
         catch (error) {
@@ -268,30 +293,33 @@ export class DHLTracker {
         }
     }
     /** The direct session, renewing a stale one or an interrupted read once. */
-    async direct(number) {
+    async direct(number, limits) {
         if (this.session !== null && this.now() - this.sessionOpenedAt >= SESSION_MAX_AGE_MS)
             this.session = null;
         const cached = this.session !== null;
         const session = this.session ?? this.open(new DHLSession(this.directTimeoutMs, this.fetcher));
         try {
-            return await session.fetch(number);
+            return await session.fetch(number, limits);
         }
         catch (error) {
             // A fresh session that was rejected outright needs a browser, not a
             // second identical attempt; a cached one may simply have expired.
             if (!renewable(error) || (!cached && !(error instanceof UpstreamNetworkError)))
                 throw error;
-            return await this.open(new DHLSession(this.directTimeoutMs, this.fetcher)).fetch(number);
+            if (over(limits.signal, limits.deadline))
+                throw error;
+            return await this.open(new DHLSession(this.directTimeoutMs, this.fetcher)).fetch(number, limits);
         }
     }
     /** A solved browser session, replayed over HTTP with its cookies and user agent. */
-    async browser(number) {
+    async browser(number, limits) {
         this.session = null;
         const trawl = this.trawl ?? new TrawlClient(this.trawlUrl, this.fetcher);
-        const solved = await trawl.scrape({ url: dhlTrackingUrl(number), skipHttp: true, maxTier: 3, maxTimeout: this.timeoutMs }, { provider: `TRAWL while fetching ${PROVIDER}`, timeoutMs: this.timeoutMs, maxBytes: 10_000_000, fetcher: this.fetcher });
+        const timeoutMs = capped(this.timeoutMs, limits);
+        const solved = await trawl.scrape({ url: dhlTrackingUrl(number), skipHttp: true, maxTier: 3, maxTimeout: timeoutMs }, { provider: `TRAWL while fetching ${PROVIDER}`, timeoutMs, maxBytes: 10_000_000, fetcher: this.fetcher, signal: limits.signal });
         const session = new DHLSession(this.directTimeoutMs, this.fetcher);
         await session.seed(solved.cookies, solved.userAgent);
-        const result = await session.fetch(number);
+        const result = await session.fetch(number, limits);
         this.open(session);
         return result;
     }
@@ -303,6 +331,6 @@ export const adapter = (environment) => {
     return {
         id: 'dhl',
         steps: ['direct', 'trawl'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/dhl-ecommerce/adapter.d.ts

@@ -14,7 +14,7 @@
  * alias, so only one eCommerce shipment from that exact request URL is
  * accepted, and the id itself is never retained.
  */
-import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
 import { ChallengeError, type CarrierErrorOptions } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
@@ -34,7 +34,7 @@ export declare class DHLEcommerceSessionError extends ChallengeError {
     readonly status: number;
     constructor(status: number, options?: CarrierErrorOptions);
 }
-export interface DHLEcommerceTrackerOptions extends UniversalBrowserOptions {
+export interface DHLEcommerceTrackerOptions extends Omit<UniversalBrowserOptions, 'signal'> {
     budgetMs?: number;
     recorder?: StepRecorder;
 }
@@ -44,7 +44,7 @@ export declare class DHLEcommerceTracker {
     private readonly serialize;
     constructor(options?: DHLEcommerceTrackerOptions);
     /** One browser at a time per instance: a batch must not spawn a Chromium per parcel. */
-    fetch(trackingNumber: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
     private browser;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/dhl-ecommerce/adapter.js

@@ -15,8 +15,8 @@
  * accepted, and the id itself is never retained.
  */
 import { DateTime } from 'luxon';
-import { ChallengeError, SchemaError } from '../../core/errors/index.js';
-import { runSteps, singleFlight } from '../../core/runner/index.js';
+import { ChallengeError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
+import { runSteps, singleFlight, takeTurn } from '../../core/runner/index.js';
 import { countryTimeZone } from '../../core/time/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { clean as cleanText, UpstreamHttpError } from '../../core/transport/index.js';
@@ -38,7 +38,7 @@ function clean(value, limit = 500) {
 export function normalizeDHLEcommerceNumber(raw) {
     const number = raw.toUpperCase().replace(/[\s.-]/g, '');
     if (!/^(?=.*\d)[A-Z0-9]{5,40}$/.test(number))
-        throw new TypeError('DHL eCommerce tracking number is invalid');
+        throw new InvalidInputError(PROVIDER, 'DHL eCommerce tracking number is invalid');
     return number;
 }
 export function dhlEcommerceTrackingUrl(number) {
@@ -146,14 +146,14 @@ export class DHLEcommerceTracker {
         this.recorder = options.recorder ?? NOOP_RECORDER;
     }
     /** One browser at a time per instance: a batch must not spawn a Chromium per parcel. */
-    async fetch(trackingNumber) {
+    async fetch(trackingNumber, context = {}) {
         const number = normalizeDHLEcommerceNumber(trackingNumber);
         const timeoutMs = this.options.timeoutMs ?? 45_000;
-        return this.serialize(() => runSteps({ carrier: 'dhl-ecommerce', budgetMs: this.options.budgetMs ?? timeoutMs + 15_000, recorder: this.recorder }, [{ id: 'browser', run: () => this.browser(number, timeoutMs) }]));
+        return takeTurn(this.serialize, PROVIDER, context, ({ signal, budgetMs }) => runSteps({ carrier: 'dhl-ecommerce', budgetMs: budgetMs ?? this.options.budgetMs ?? timeoutMs + 15_000, signal, recorder: this.recorder }, [{ id: 'browser', run: (step) => this.browser(number, Math.max(1, Math.floor(Math.min(timeoutMs, step.remainingMs))), step.signal) }]));
     }
-    async browser(number, timeoutMs) {
+    async browser(number, timeoutMs, signal) {
         try {
-            return await scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs }, {
+            return await scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs, signal }, {
                 name: PROVIDER, url: dhlEcommerceTrackingUrl(number), responseUrl: trackingApiUrl(number),
             }, parseDHLEcommerceResponse);
         }
@@ -174,6 +174,6 @@ export const adapter = (environment) => {
     return {
         id: 'dhl-ecommerce',
         steps: ['browser'],
-        track: (input) => tracker.fetch(input.number),
+        track: (input, context) => tracker.fetch(input.number, context),
     };
 };

package/dist/carriers/dpd/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, IndeterminateError, NotFoundError, type CarrierErrorOptions } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import type { StepRecorder } from '../../core/telemetry/index.js';
@@ -45,7 +45,7 @@ export declare class DPDTracker {
     constructor(options?: DPDTrackerOptions);
     /** The browser service, resolved late so a malformed URL fails the page step, not construction. */
     private browserService;
-    fetch(trackingNumber: string, postcode?: string): Promise<CarrierResult>;
+    fetch(trackingNumber: string, postcode?: string, context?: TrackingContext): Promise<CarrierResult>;
     /**
      * Whether DPD knows a 14-digit number, for the host's carrier-detection
      * route, which promotes the number to `dpd` only when this returns true.
@@ -54,7 +54,7 @@ export declare class DPDTracker {
      * parcels) are false; any other failure, a 400 from a token step included,
      * stays a failure.
      */
-    recognizes(trackingNumber: string): Promise<boolean>;
+    recognizes(trackingNumber: string, context?: TrackingContext): Promise<boolean>;
     private apiFetch;
     private detailsWithFreshToken;
     private parcelDetails;