universal-parcel-scraper 0.2.0 → 0.2.1-main.296

package/README.md

@@ -1,124 +1,257 @@
 <div align="center">
 
+<img src="docs/assets/logo.svg" width="88" alt="">
+
 # Universal Parcel Scraper
 
-**A parcel. One timeline. Your infrastructure.**
+**Parcel tracking that asks the carrier directly, from your own machine.**
 
+[![npm](https://img.shields.io/npm/v/universal-parcel-scraper)](https://www.npmjs.com/package/universal-parcel-scraper)
 [![CI](https://github.com/plhery/universal-parcel-scraper/actions/workflows/ci.yml/badge.svg)](https://github.com/plhery/universal-parcel-scraper/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
-Detect a carrier, fetch its tracking history, and get consistent stages and scan times.
-A TypeScript library, a CLI, and a small HTTP server. No tracking-service account required.
-
 <!-- GENERATED:summary -->
 **105 carriers · 85 active dedicated adapters · 58 countries represented**
 <!-- /GENERATED:summary -->
 
+[Try it](#try-it) · [Ways to run it](#ways-to-run-it) · [Coverage](#how-much-can-it-track) · [Carriers](carriers/) · [Add a carrier](CONTRIBUTING.md)
+
+<img src="docs/assets/demo.svg" width="840" alt="The track command printing a parcel's history as JSON, next to a timeline drawn from it">
+
 </div>
 
-DHL, UPS, FedEx, USPS, Swiss Post, DPD, PostNL, and many more.
-[Browse the carriers](carriers/) · [How it works](ARCHITECTURE.md) · [Add a carrier](CONTRIBUTING.md)
+Give it a tracking number. It works out which carrier the number belongs to and fetches the
+history from that carrier's own website. What comes back has one shape, so a UPS parcel and
+a Poczta Polska parcel look the same to your code.
+
+There is no account to open and no API key. Every carrier publishes tracking in its own way,
+and hosted tracking APIs smooth that over for a fee while seeing every number you look up.
+Here the same work is open code: one adapter per carrier, each in [its own folder](carriers/)
+with a README on how that site is read.
 
-## Get started
+## Try it
 
-Node.js 24 or newer:
+You need Node.js 24 or newer.
 
 ```sh
-npm install universal-parcel-scraper
-npx parcel-scraper detect 1Z999AA10123456784
-npx parcel-scraper track YOUR_TRACKING_NUMBER --carrier ups
+npx universal-parcel-scraper detect 1Z999AA10123456784
 ```
 
-```js
-import { createTracker } from 'universal-parcel-scraper/node';
+Detection is offline. It checks the number against each carrier's formats and checksums and
+answers `ups` without sending anything anywhere.
 
-const tracker = createTracker();
-const { carrier, source, result } = await tracker.track({
-  number: process.env.PARCEL_NUMBER,
-  carrier: 'ups',
-});
-console.log(carrier, source, result.current_stage, result.events);
+```sh
+npx universal-parcel-scraper track YOUR_TRACKING_NUMBER
 ```
 
-Detection also works in the browser, with no network calls:
+Tracking does go out, to the carrier that owns the number. If a number fits several carriers,
+name one with `--carrier dhl`. A few carriers also want the delivery postcode (`--postcode`)
+or the link from the shipping email (`--tracking-url`).
 
-```js
-import { parseTrackingInput } from 'universal-parcel-scraper';
-const match = parseTrackingInput('1Z999AA10123456784'); // synthetic example
+## Ways to run it
+
+### Command line
+
+```sh
+npm install -g universal-parcel-scraper
 ```
 
-Direct HTTP works out of the box. Some carriers need Chromium, image processing, or the
-optional [TRAWL browser service](trawl/README.md). Install the transports you need:
+The command is `parcel-scraper`:
 
 ```sh
-npm install playwright-core sharp onnxruntime-web
+parcel-scraper detect <number, link or text>   # which carrier is this? no network
+parcel-scraper track <number>                  # the parcel's history
+parcel-scraper recognize <number>              # ask the possible carriers which one knows it
+parcel-scraper carriers                        # the catalog, with the ids --carrier accepts
+parcel-scraper serve                           # the HTTP API described below
 ```
 
-Pass `chromiumPath` or `trawlUrl` to `createTracker()`. Commercial aggregators are opt-in:
-`createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', 'UPU'] })`.
-The default is direct adapters plus UPU for eligible postal numbers.
+Everything prints JSON, so it pipes:
 
-## How much can it track?
+```sh
+parcel-scraper track "$NUMBER" | jq -r '.result.current_stage'
+```
 
-Carrier count tells you what the catalog knows. Tracking history tells you what a source
-actually returned. Here is the recorded comparison on our **100-carrier reference set**:
+`parcel-scraper --help` lists the environment variables.
 
-<!-- GENERATED:coverage -->
-| Source | Carriers with history |
-| --- | ---: |
-| **Universal Parcel Scraper, all fallbacks enabled** | **70 / 100** |
-| Dedicated adapters alone | 51 / 100 |
-| ParcelsApp | 50 / 100 |
-| Postal Ninja | 41 / 100 |
-| 17TRACK | 40 / 100 |
-| Ship24 | 38 / 100 |
-| UPU | 11 / 100 |
-<!-- /GENERATED:coverage -->
+### Node
+
+```js
+import { createTracker } from 'universal-parcel-scraper/node';
+
+const tracker = createTracker();
+const { carrier, source, result } = await tracker.track({ number: process.env.PARCEL_NUMBER });
+
+console.log(carrier, result.current_stage);
+for (const scan of result.events) {
+  console.log(scan.time, scan.location, scan.description, scan.stage);
+}
+```
+
+Each scan keeps the carrier's wording and gains a `stage` from [one shared list](data/stages.json).
+`source` names who answered, and `attempts` lists everything that was tried. When nothing
+returns a history, `track()` throws a `TrackingError` carrying those attempts and a hint about
+the cause. [examples/node.mjs](examples/node.mjs) is a runnable version.
+
+### Browser
+
+```js
+import { parseTrackingInput } from 'universal-parcel-scraper';
+
+parseTrackingInput('1Z999AA10123456784');
+// { carrier: 'ups', confidence: 'high', candidates: ['ups'], … }
+```
+
+The root import has no Node imports and makes no requests, so it can sit behind a form field
+and name the carrier as someone types.
 
-Generated from [coverage.json](providers/coverage.json). These are recorded outcomes for
-the comparison reference of each carrier, including partial histories; alternate samples
-are excluded. This curated set is not a global market-share ranking or a live availability
-promise. Old parcels expire, formats differ, and browser challenges change.
-[Full results and limitations](providers/COVERAGE.md).
+### HTTP
 
-Hosted APIs advertise much larger carrier catalogs and handle hosting for you. This project
-gives you the retrieval code, control over which sources receive a number, and no per-lookup
-subscription. Catalog totals from vendors are not comparable to this reference test.
+For anything that is not JavaScript:
 
-## HTTP, Docker, and Home Assistant
+```sh
+parcel-scraper serve --port 8080
+```
 
 ```sh
-npx parcel-scraper serve --port 8080
 curl http://127.0.0.1:8080/v1/track \
   -H 'Content-Type: application/json' \
   -d '{"number":"1Z999AA10123456784","carrier":"ups"}'
 ```
 
-The server shares cached answers, spaces universal-provider calls, and limits requests.
-It stores no parcel list and runs no background polling. Set `SCRAPER_TOKEN` for bearer
-authentication, `SCRAPER_PROVIDERS` to select fallbacks, and `SCRAPER_DEMO_PAGE=true` for a
-small one-off tracking page. [HTTP contract](server/openapi.json) · [Configuration](.env.example).
+`/v1/detect`, `/v1/recognize` and `/v1/carriers` sit next to it, and the
+[OpenAPI file](server/openapi.json) describes them all. The server caches recent answers in
+memory and rate-limits callers. It has no database and never polls on its own.
+
+Set `SCRAPER_TOKEN` to require a bearer token. `SCRAPER_DEMO_PAGE=true` serves a small page
+at `/` for trying numbers by hand. The other settings are in [.env.example](.env.example).
 
-The versioned container includes Chromium and the optional transports:
+### Docker
 
 ```sh
 docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/plhery/universal-parcel-scraper:0.2.0
 ```
 
-A [Home Assistant REST sensor](examples/home-assistant.yaml) can call the same API.
-[Node example](examples/node.mjs) · [Development](CONTRIBUTING.md).
+The image runs `serve` and ships Chromium, for the carriers that only answer a real browser.
+
+## What you can build with it
+
+- **A tracking screen in your own app.** [Delivery Tracker](https://github.com/plhery/delivery-tracker),
+  an open-source iPhone app and PWA, runs on this package.
+- **A Home Assistant sensor** for the parcel you are waiting on.
+  [The config is in examples](examples/home-assistant.yaml).
+- **Order status inside a shop or help desk**, so customers are not sent off to the carrier's
+  site. Any backend that speaks HTTP can call the server.
+- **Tracking numbers pulled out of shipping emails.** `detect` takes pasted text and carrier
+  links as well as bare numbers.
+- **A carrier field that fills itself in**, with the browser import.
+- **A cron job** that pings you when `current_stage` turns `delivered`.
 
-## Data and limits
+The library answers one lookup at a time. Storing parcels and deciding when to check again
+are yours to do.
 
-Lookups send the tracking number and any required postcode or capability URL to the selected
-carrier. Enabled commercial fallbacks receive the number; ParcelsApp also receives a supplied
-postcode. A configured TRAWL instance handles the requested pages. Browser pages can load the
-carrier's or provider's challenge resources. The library has no telemetry destination;
-HTTP logs contain route names and outcomes, never parcel inputs.
+## How it works
 
-Consumers own polling and persistence. Respect the catalog's refresh limits and the upstream
-retry advice. Carrier sites can change or refuse automated requests; some need a postcode,
-a full tracking link, or an account and remain limited. Unresolved local clocks stay unresolved.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/how-it-works-dark.svg">
+  <img src="docs/assets/how-it-works-light.svg" width="840" alt="An input is detected offline and tracked by the carrier's dedicated adapter. With no history, the lookup moves to the fallbacks you enabled. Either way the result is one timeline.">
+</picture>
+
+Each adapter uses plain HTTP wherever the carrier's site allows it. Some sites only answer a
+real browser and others need image processing, so those adapters can drive a local Chromium
+or the optional [TRAWL browser service](trawl/README.md). Install what your carriers need:
+
+```sh
+npm install playwright-core sharp onnxruntime-web
+```
+
+Then pass `chromiumPath` or `trawlUrl` to `createTracker()`. The CLI and the server read
+`TRACKING_CHROMIUM_PATH` and `FLARESOLVERR_URL`.
+
+When the adapter finds no history, the lookup can move on to an aggregator. Only UPU is on
+by default, for the postal numbers it can serve. The commercial ones are opt-in, and each
+one you enable receives the tracking number:
+
+```js
+createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', 'UPU'] });
+```
+
+[ARCHITECTURE.md](ARCHITECTURE.md) has the rest.
+
+## How much can it track?
+
+A carrier count says what the catalog knows about. Whether a real parcel comes back with its
+history is a different question, so each source was run on its own against the same
+**100-carrier reference set**. The top bar counts a carrier when any source below it returned
+a history.
+
+<!-- GENERATED:coverage -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/coverage-dark.svg">
+  <img src="docs/assets/coverage-light.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 70, This project, dedicated adapters alone 51, ParcelsApp 50, Postal Ninja 41, 17TRACK 40, Ship24 38, UPU 11." width="760">
+</picture>
+
+<details>
+<summary>The same numbers as a table</summary>
+
+| Source | Carriers with history |
+| --- | ---: |
+| **Universal Parcel Scraper, all fallbacks enabled** | **70 / 100** |
+| Dedicated adapters alone | 51 / 100 |
+| ParcelsApp | 50 / 100 |
+| Postal Ninja | 41 / 100 |
+| 17TRACK | 40 / 100 |
+| Ship24 | 38 / 100 |
+| UPU | 11 / 100 |
+
+</details>
+<!-- /GENERATED:coverage -->
 
-The core is [Apache-2.0](LICENSE). The optional TRAWL derivative is [AGPL-3.0](trawl/LICENSE).
-Data and model credits are in [NOTICE](NOTICE).
+The numbers come from [coverage.json](providers/coverage.json): the recorded outcome for each
+carrier's comparison reference, partial histories included and alternate samples left out.
+The set is curated. Read it as a comparison between sources, not as a market-share ranking
+or a promise about today, because parcels expire and carrier sites change.
+[Carrier-by-carrier results and limitations](providers/COVERAGE.md).
+
+## Next to a hosted tracking API
+
+| | Universal Parcel Scraper | Hosted tracking API |
+| --- | --- | --- |
+| Account | None | Sign-up and an API key |
+| Cost | Your own compute | A plan or a per-shipment price |
+| Who sees the tracking number | The carrier, plus any fallback you enable | The vendor, then the carrier |
+| Carriers | The [catalog](carriers/) in this repository | A much larger catalog |
+| Updates | You poll | Webhooks |
+| When a carrier changes its site | The adapter breaks until it is fixed here | The vendor deals with it |
+| Hosting | Yours | Theirs |
+
+If you want the widest catalog and nothing to run, a hosted API is the better choice. This
+project is for when the numbers should stay on your side, or when a price per parcel makes
+no sense for what you are building. Vendor catalog totals are not comparable with the
+reference test above.
+
+## Privacy and limits
+
+A lookup sends the tracking number to the carrier, along with the postcode or tracking link
+when that carrier requires one. Fallbacks you enabled receive the number too, and ParcelsApp
+also gets a postcode if you supplied it. Pages opened in a browser, locally or through TRAWL,
+can load the carrier's or provider's challenge scripts. The library has no telemetry, and
+the server's logs hold route names and outcomes, never parcel inputs.
+
+This is scraping, so things break. Carriers redesign their sites and turn away automated
+requests. A few need more than the number, such as a postcode or the link from the shipping
+email, and the ones that require an account stay limited. Keep to the catalog's refresh
+limits and to the retry advice that comes with an error. A scan time with no known UTC offset
+is returned as the carrier wrote it, with no zone guessed.
+
+## Contributing
+
+Adapters break when carriers change their sites. Each carrier lives in its own folder with
+synthetic fixtures and offline tests, so a fix stays local to that folder. For a new carrier,
+`npm run carrier:new` scaffolds the folder and [CONTRIBUTING.md](CONTRIBUTING.md) covers the
+rest. Report security issues through [SECURITY.md](SECURITY.md).
+
+## License
+
+The core is [Apache-2.0](LICENSE). The optional TRAWL image is a derivative under
+[AGPL-3.0](trawl/LICENSE). Data and model credits are in [NOTICE](NOTICE).

package/data/carrier.schema.json

@@ -205,7 +205,7 @@
           "minLength": 1
         },
         "canaryUrl": {
-          "description": "Public, credential-free HTTPS URL the daily canary probes. Required for automatic carriers.",
+          "description": "Public, credential-free HTTPS URL the weekly canary probes. Required for automatic carriers.",
           "type": "string"
         },
         "shows": {

package/dist/carriers/dachser/adapter.js

@@ -136,10 +136,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)

package/dist/carriers/dpd/adapter.js

@@ -797,6 +797,8 @@ export const adapter = (environment) => {
         fetcher: environment.fetcher,
         trawl: environment.trawl,
         recorder: environment.recorder,
+        // A host can follow a rotated key without waiting for a release.
+        firebaseApiKey: environment.env.DPD_FIREBASE_API_KEY?.trim() || undefined,
     });
     return {
         id: 'dpd',

package/dist/carriers/mrw/adapter.js

@@ -51,8 +51,10 @@ export class MrwTracker {
                     const deadline = performance.now() + remainingMs;
                     const jar = new Map();
                     let requests = 0;
+                    // The step's signal ends at the budget too, and its timer can fire just before the deadline reads as passed.
+                    const spent = () => performance.now() >= deadline || (signal.aborted && !context.signal?.aborted);
                     const ensureTime = () => {
-                        if (performance.now() >= deadline)
+                        if (spent())
                             throw new BudgetExceededError('MRW', budgetMs);
                         signal.throwIfAborted();
                     };
@@ -72,7 +74,7 @@ export class MrwTracker {
                             }, this.options.paceMs ?? PACE_MS);
                             signal.addEventListener('abort', abort, { once: true });
                         }).catch(error => {
-                            if (performance.now() >= deadline)
+                            if (spent())
                                 throw new BudgetExceededError('MRW', budgetMs, { cause: error });
                             throw error;
                         });

package/dist/cli/index.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
 export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+/** What a failed command prints: a rejected input, setting or listener explains itself; anything else stays generic. */
+export declare function failureText(error: unknown): string;

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
+import { InputRequiredError } from '../core/errors/index.js';
 import { createTracker, TrackingError } from '../facade/index.js';
 import { CARRIER_CATALOG } from '../generated/catalog.js';
 import { createTrackingServer } from '../server/index.js';
@@ -21,6 +22,8 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         console.log(help);
         return 0;
     }
+    if (!['detect', 'recognize', 'track', 'carriers', 'serve'].includes(command))
+        throw new TypeError('Unknown command; use --help');
     const values = {};
     const positional = [];
     const allowed = command === 'track' ? ['carrier', 'postcode', 'tracking-url'] : command === 'serve' ? ['host', 'port'] : [];
@@ -32,19 +35,30 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         }
         const name = argument.slice(2);
         if (!allowed.includes(name) || !args[i + 1] || args[i + 1].startsWith('--'))
-            throw new TypeError('Unknown or incomplete command option');
+            throw new TypeError('Unknown or incomplete command option; use --help');
         values[name] = args[++i];
     }
-    const providers = env.SCRAPER_PROVIDERS === undefined ? undefined
-        : env.SCRAPER_PROVIDERS.split(',').map(value => value.trim()).filter(Boolean);
-    const options = { providers, trawlUrl: env.FLARESOLVERR_URL, chromiumPath: env.TRACKING_CHROMIUM_PATH, env };
-    const tracker = createTracker(options);
     const print = (value) => console.log(JSON.stringify(value, null, 2));
-    if (command === 'carriers' && positional.length === 0) {
+    const input = positional.join(' ');
+    if (command === 'carriers' || command === 'serve') {
+        if (input)
+            throw new TypeError('Unexpected argument; use --help');
+    }
+    else if (!input)
+        throw new TypeError('Supply a tracking input; use --help');
+    // The catalog and detection are offline: the transport settings below cannot break them.
+    if (command === 'carriers') {
         print(CARRIER_CATALOG);
         return 0;
     }
-    if (command === 'serve' && positional.length === 0) {
+    if (command === 'detect') {
+        print(createTracker().detect(input));
+        return 0;
+    }
+    const providers = env.SCRAPER_PROVIDERS === undefined ? undefined
+        : env.SCRAPER_PROVIDERS.split(',').map(value => value.trim()).filter(Boolean);
+    const options = { providers, trawlUrl: env.FLARESOLVERR_URL, chromiumPath: env.TRACKING_CHROMIUM_PATH, env };
+    if (command === 'serve') {
         const port = Number(values.port ?? env.PORT ?? 8080);
         if (!Number.isInteger(port) || port < 1 || port > 65535)
             throw new TypeError('Invalid port');
@@ -57,26 +71,26 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
             process.once(signal, () => server.close());
         return 0;
     }
-    const input = positional.join(' ');
-    if (!input)
-        throw new TypeError('Supply a tracking input');
-    if (command === 'detect')
-        print(tracker.detect(input));
-    else if (command === 'recognize')
+    const tracker = createTracker(options);
+    if (command === 'recognize')
         print(await tracker.recognize(input));
-    else if (command === 'track')
-        print(await tracker.track({ number: input, carrier: values.carrier, postcode: values.postcode, trackingUrl: values['tracking-url'] }));
     else
-        throw new TypeError('Unknown command; use --help');
+        print(await tracker.track({ number: input, carrier: values.carrier, postcode: values.postcode, trackingUrl: values['tracking-url'] }));
     return 0;
 }
+/** What a failed command prints: a rejected input, setting or listener explains itself; anything else stays generic. */
+export function failureText(error) {
+    if (error instanceof TrackingError)
+        return JSON.stringify({ error: error.message, attempts: error.attempts, hint: error.hint });
+    return error instanceof TypeError || error instanceof RangeError || error instanceof InputRequiredError
+        || (error instanceof Error && 'syscall' in error) ? error.message : 'Tracking could not be completed';
+}
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
     try {
         process.exitCode = await main();
     }
     catch (error) {
-        console.error(error instanceof TrackingError ? JSON.stringify({ error: error.message, attempts: error.attempts, hint: error.hint })
-            : error instanceof TypeError ? 'Invalid input or command; use --help' : 'Tracking could not be completed');
+        console.error(failureText(error));
         process.exitCode = 1;
     }
 }

package/dist/core/catalog/urls.js

@@ -5,6 +5,7 @@ const PLANZER_ACCESS_KEY = /^[A-Za-z0-9_-]{32,256}$/;
 const DACHSER_HOST = 'customeriberia.dachser.com';
 const DACHSER_PAGE_PATH = '/customerarea/utilidades/seguimiento-publico/detalle';
 const CAPABILITY_VALUE = /^[A-Za-z0-9_-]{4,256}$/;
+// eslint-disable-next-line no-control-regex -- control characters are what this rejects
 const CONTROL_CHARACTER = /[\x00-\x1f\x7f]/;
 const ALLOWED_QUERY_KEYS = new Set([
     'hash',

package/dist/facade/index.js

@@ -98,9 +98,12 @@ export function createTracker(options = {}) {
             throw new TypeError('Invalid tracking number');
         const number = normalizeTrackingNumber(raw);
         const ms = budget(context.budgetMs, 10_000);
+        // The budget cancels what is still in flight and ends the wait: carriers that have not
+        // answered by then are reported as unanswered. Only the caller's own signal rejects.
         const signal = context.signal ? AbortSignal.any([context.signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms);
-        const candidates = recognitionCandidates(number).filter(candidate => registry.for(candidate.carrier)?.recognize);
-        const outcomes = await bounded(() => lookupSignals.run(signal, () => recognizeAll(candidates, carrier => registry.for(carrier).recognize(number, { signal, budgetMs: ms }), ms)), signal);
+        const candidates = recognitionCandidates(number).filter(candidate => typeof registry.for(candidate.carrier)?.recognize === 'function');
+        const ask = () => lookupSignals.run(signal, () => recognizeAll(candidates, carrier => registry.for(carrier).recognize(number, { signal, budgetMs: ms }), ms));
+        const outcomes = await (context.signal ? bounded(ask, context.signal) : ask());
         return { ...settleRecognition(outcomes), asked: candidates.map(candidate => candidate.carrier),
             unanswered: outcomes.filter(outcome => outcome.status === 'failed').map(outcome => outcome.carrier) };
     }
@@ -127,8 +130,13 @@ export function createTracker(options = {}) {
                     throw new InputRequiredError('Tracking', 'carrier', 'Choose a carrier for this number');
             }
             catch (error) {
-                if (signal.aborted || error instanceof InputRequiredError)
+                if (context.signal?.aborted)
+                    throw context.signal.reason;
+                if (error instanceof InputRequiredError)
                     throw error;
+                // Recognition used the whole budget: no source was asked, and that is the failure to report.
+                if (signal.aborted)
+                    throw new TrackingError([], failureHint(new BudgetExceededError('Tracking', ms)));
             }
         }
         if (input.postcode != null && typeof input.postcode !== 'string')
@@ -159,7 +167,7 @@ export function createTracker(options = {}) {
         const adapter = registry.for(carrier);
         const directInput = { number, postcode: fields.dpdPostcode, trackingUrl: fields.trackingUrl };
         const directBudget = () => Math.min(remaining(), 60_000);
-        let result = adapter ? await attempt(carrier, () => adapter.steps.length > 1
+        let result = adapter ? await attempt(carrier, () => adapter.recordsSteps || adapter.steps.length > 1
             ? adapter.track(directInput, { signal, budgetMs: directBudget() })
             : runSteps({ carrier, budgetMs: directBudget(), signal, recorder: environment.recorder }, [
                 { id: adapter.steps[0] ?? 'direct', run: ({ signal: stepSignal, remainingMs }) => adapter.track(directInput, { signal: stepSignal, budgetMs: remainingMs }) },

package/dist/providers/postal-ninja/adapter.js

@@ -5,8 +5,8 @@
  * opens the normal results page for its verified handle and captures the full
  * `/track/get` response. Local Chromium without TRAWL retains compact widget
  * capture. The main entry form has a separate verification gate.
- * The provider is disabled by default;
- * `TRACKING_ENABLE_POSTAL_NINJA=true` puts it in the chain before 17TRACK.
+ * The provider is disabled by default; selecting `Postal Ninja` in `providers`
+ * puts it in the chain before 17TRACK.
  */
 import { DateTime } from 'luxon';
 import { ChallengeError, NoHistoryError, SchemaError } from '../../core/errors/index.js';
@@ -109,6 +109,7 @@ export class PostalNinjaTracker {
                 && payload.track.state === 'NO_INFO' && !payload.inProgress) {
                 return new NoHistoryError(SOURCE, 'Postal Ninja has no available tracking history');
             }
+            return undefined;
         };
         return runSteps({ carrier: SOURCE, budgetMs: timeoutMs, recorder: this.options.recorder }, [{
                 id: 'trawl', enabled: Boolean(this.options.trawl),

package/dist/providers/ship24/adapter.js

@@ -5,10 +5,11 @@
  * Two tiers: `direct` is one signed anonymous JSON POST per lookup (see
  * http.ts), `browser` loads the public tracking page in a local Chromium
  * session and reads the same API response from it. The browser tier only runs
- * when the direct tier failed for a reason a browser can repair: a rate limit
- * or a server outage is reported as it is, so the router's backoff is not
- * amplified into a second request, and a number the aggregator does not know
- * stays unknown to the page that asks the same API.
+ * when a Chromium is configured and the direct tier failed for a reason a
+ * browser can repair: a rate limit or a server outage is reported as it is, so
+ * the router's backoff is not amplified into a second request, and a number
+ * the aggregator does not know stays unknown to the page that asks the same
+ * API.
  */
 import { DateTime } from 'luxon';
 import { carrierTimezone } from '../../core/catalog/index.js';
@@ -114,6 +115,9 @@ export class Ship24Tracker {
             },
             {
                 id: 'browser',
+                // Without a Chromium this tier could only replace the direct failure
+                // with its own configuration error. Alone, it still runs to report it.
+                enabled: http === null || Boolean(this.options.executablePath),
                 recovers: browserCanRecover,
                 run: async ({ remainingMs }) => ({
                     ...await scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs: Math.max(1, Math.floor(remainingMs)) }, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.2.0",
+  "version": "0.2.1-main.296",
   "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,15 +27,15 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./node": {
       "types": "./dist/node.d.ts",
-      "import": "./dist/node.js"
+      "default": "./dist/node.js"
     },
     "./places": {
       "types": "./dist/places/index.d.ts",
-      "import": "./dist/places/index.js"
+      "default": "./dist/places/index.js"
     },
     "./data/*": "./data/*"
   },
@@ -54,7 +54,7 @@
     "build": "node scripts/build.mjs",
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint . --max-warnings=0",
+    "lint": "eslint . --max-warnings=0 --pass-on-unpruned-suppressions",
     "test": "vitest run",
     "test:scripts": "node --test trawl/*.test.mjs scripts/*.test.mjs",
     "generate": "node scripts/generate-catalog.mjs && node scripts/generate-registry.mjs --strict && node scripts/generate-region-towns.mjs && node scripts/coverage-tables.mjs && node scripts/generate-readme.mjs",
@@ -98,7 +98,9 @@
     "@types/node": "^26.6.3",
     "@types/luxon": "^3.7.5",
     "ajv": "^8.20.0",
-    "eslint": "^9.39.5",
-    "@typescript-eslint/parser": "^8.71.0"
+    "eslint": "^10.12.0",
+    "@eslint/js": "^10.0.1",
+    "typescript-eslint": "^8.71.0",
+    "globals": "^17.13.0"
   }
 }