universal-parcel-scraper 0.3.0-main.303 → 0.3.0-main.308

package/README.md

@@ -18,44 +18,39 @@ The engine behind [Peek](https://github.com/plhery/delivery-tracker), the open-s
 <sub>105 carriers in the catalog · 58 countries represented</sub>
 <!-- /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)
+[Try it](#try-it) · [Ways to run it](#ways-to-run-it) · [Benchmark](#benchmark) · [Carriers](carriers/) · [Add a carrier](CONTRIBUTING.md)
 
 <img src="docs/assets/terminal.svg" width="840" alt="A terminal session: the detect command names UPS as the carrier of a tracking number, then the track command prints a parcel's scans with their stages">
 
 </div>
 
-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.
+Give it a tracking number. It finds the carrier, fetches the history from the carrier's own
+site and returns the same JSON for every carrier. No account, no API key.
 
-There is no account to open and no API key. The carriers it knows best each have a dedicated
-adapter in [their own folder](carriers/), with a README on how that site is read. For the
-rest it can ask the universal trackers such as 17TRACK and Ship24, which is where the big
-number above comes from. Those stay off until you switch them on, and each one you enable
-sees the numbers you send it.
+It is the tracking engine of [Peek](https://github.com/plhery/delivery-tracker), usable on
+its own as a command, a Node library or an HTTP server.
 
-It started as the tracking engine inside [Peek](https://github.com/plhery/delivery-tracker)
-and was pulled out so it can be used on its own. It runs as a command-line tool and as a Node
-library, and it can serve the same lookups over HTTP.
+## Benchmark
 
-## Try it
+<!-- GENERATED:coverage -->
+Benchmarked against 100 popular carriers, it returns tracking history for **70**. The best single aggregator returns 50.
 
-You need Node.js 24 or newer.
+<img src="docs/assets/coverage.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">
+<!-- /GENERATED:coverage -->
 
-```sh
-npx universal-parcel-scraper detect 1Z999AA10123456784
-```
+[Method and results per carrier](providers/COVERAGE.md)
 
-Detection is offline. It checks the number against each carrier's formats and checksums and
-answers `ups` without sending anything anywhere.
+## Try it
+
+Needs Node.js 24 or newer.
 
 ```sh
-npx universal-parcel-scraper track YOUR_TRACKING_NUMBER
+npx universal-parcel-scraper detect 1Z999AA10123456784    # offline: names the carrier
+npx universal-parcel-scraper track YOUR_TRACKING_NUMBER   # asks the carrier
 ```
 
-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`).
+Add `--carrier dhl` when a number fits several carriers. Some carriers also want
+`--postcode` or `--tracking-url`.
 
 ## Ways to run it
 
@@ -65,23 +60,15 @@ or the link from the shipping email (`--tracking-url`).
 npm install -g universal-parcel-scraper
 ```
 
-The command is `parcel-scraper`:
-
 ```sh
 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
-```
-
-Everything prints JSON, so it pipes:
-
-```sh
-parcel-scraper track "$NUMBER" | jq -r '.result.current_stage'
+parcel-scraper serve                           # the HTTP API
 ```
 
-`parcel-scraper --help` lists the environment variables.
+Output is JSON, so it pipes into `jq`. `parcel-scraper --help` lists the environment variables.
 
 ### Node
 
@@ -97,10 +84,8 @@ for (const scan of result.events) {
 }
 ```
 
-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.
+`source` names who answered and `attempts` lists what was tried. With no history, `track()`
+throws a `TrackingError` carrying both. [Runnable example](examples/node.mjs).
 
 ### Browser
 
@@ -111,143 +96,65 @@ 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.
-
-### HTTP
+Detection has no Node imports and makes no requests.
 
-For anything that is not JavaScript:
+### HTTP and Docker
 
 ```sh
 parcel-scraper serve --port 8080
 ```
 
 ```sh
-curl http://127.0.0.1:8080/v1/track \
-  -H 'Content-Type: application/json' \
-  -d '{"number":"1Z999AA10123456784","carrier":"ups"}'
+docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/plhery/universal-parcel-scraper:0.3.0
 ```
 
-`/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. Behind a reverse proxy, set `SCRAPER_TRUSTED_PROXIES` so
-the rate limit counts each caller and not the proxy. The other settings are in
-[.env.example](.env.example).
-
-### Docker
-
 ```sh
-docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/plhery/universal-parcel-scraper:0.3.0
+curl http://127.0.0.1:8080/v1/track \
+  -H 'Content-Type: application/json' \
+  -d '{"number":"1Z999AA10123456784","carrier":"ups"}'
 ```
 
-The image runs `serve` and ships Chromium, for the carriers that only answer a real browser.
+The server caches answers in memory and rate-limits callers. It has no database and never
+polls. The image ships Chromium. Routes are in the [OpenAPI file](server/openapi.json) and
+settings, such as `SCRAPER_TOKEN` and `SCRAPER_TRUSTED_PROXIES`, in [.env.example](.env.example).
 
 ## What you can build with it
 
-- **A parcel-tracking app.** [Peek](https://github.com/plhery/delivery-tracker) is the
-  full-size example: an iPhone and web app built 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`.
+- A parcel-tracking app, like [Peek](https://github.com/plhery/delivery-tracker).
+- A [Home Assistant sensor](examples/home-assistant.yaml) for the parcel you are waiting on.
+- Order status inside a shop or help desk, from any backend that speaks HTTP.
+- Tracking numbers pulled out of shipping emails: `detect` reads pasted text and links.
+- A cron job that pings you when `current_stage` turns `delivered`.
 
-The library answers one lookup at a time. Storing parcels and deciding when to check again
-are yours to do.
+It answers one lookup at a time. Storing parcels and polling are yours.
 
 ## How it works
 
-<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 fetched by the carrier's dedicated adapter, or by a fallback you enabled when that finds no history. Each scan's wording is filed under a stage, and 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:
+<img src="docs/assets/how-it-works.svg" width="840" alt="An input is detected offline and fetched by the carrier's dedicated adapter, or by a fallback you enabled when that finds no history. Each scan's wording is filed under a stage, and the result is one timeline.">
 
-```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`.
+**Fetching.** Adapters use plain HTTP where the site allows it. For sites that only answer a
+browser, install `playwright-core sharp onnxruntime-web` and pass `chromiumPath`, or run the
+[TRAWL browser service](trawl/README.md) and pass `trawlUrl`. Pass `userAgent` to name your
+install to carriers.
 
-Where a carrier accepts a plain client, the adapter names itself with the package's default
-User-Agent. Pass `userAgent`, or set `SCRAPER_USER_AGENT`, to send your own.
-
-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:
+**Fallbacks.** When an adapter finds no history, the lookup moves to the universal trackers
+you enabled. Only UPU is on by default. Each one you enable receives the tracking number.
 
 ```js
 createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', 'UPU'] });
 ```
 
-### One stage list
-
-Carriers describe the same moment in their own words, or with a bare code. Each carrier
-folder keeps a `statuses.json` with the codes and wordings seen from that carrier and the
-stage each one means. Every entry also says how it was confirmed, by a live reply or the
-carrier's own documentation for instance.
+**Stages.** Carriers word the same moment differently. Every scan is filed under one stage:
 
 <!-- GENERATED:stages -->
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/stages-dark.svg">
-  <img src="docs/assets/stages-light.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
-</picture>
+<img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The folders hold 1,671 recorded statuses from 88 carriers.
+The carrier folders record 1,672 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
-A scan nobody has recorded yet goes through a shared classifier that reads English, French,
-German, Italian, Spanish, Portuguese and Polish. Each scan in the result carries a
-`stage_source` saying which of the two decided.
-
+Wording nobody recorded yet goes through a classifier that reads seven European languages.
 [ARCHITECTURE.md](ARCHITECTURE.md) has the rest.
 
-## How much can it track?
-
-The number at the top of this page is reach: with the fallbacks on, a lookup can go to the
-largest aggregator, and [reach.json](docs/reach.json) records how many carriers each one
-says it follows. 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 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 |
@@ -255,38 +162,25 @@ or a promise about today, because parcels expire and carrier sites change.
 | 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 | Dedicated adapters for the [catalog](carriers/), fallbacks for the rest | One large 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 webhooks 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.
+- A lookup sends the number to the carrier, with the postcode or tracking link when the
+  carrier requires one. Enabled fallbacks receive the number too.
+- No telemetry. Server logs hold route names and outcomes, never parcel inputs.
+- This is scraping: carriers change their sites and turn away automated requests. Keep to the
+  catalog's refresh limits and to the retry advice in errors.
+- A scan time with no known UTC offset is returned as the carrier wrote it.
 
 ## 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).
+Each carrier lives in its own folder with synthetic fixtures and offline tests.
+`npm run carrier:new` scaffolds a new one. See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[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).
+[Apache-2.0](LICENSE). The optional TRAWL image is [AGPL-3.0](trawl/LICENSE). Credits are in
+[NOTICE](NOTICE).

package/dist/app.d.ts

@@ -1,13 +1,14 @@
 /**
  * Helpers shaped for the parcel app this package was extracted from: its
  * parcel view, carrier-name hints for provider results, the clock helpers
- * its sync uses, and the country a scan's location names. They change with
- * that app and carry no stability promise; the tracking contract is the
- * other entry points.
+ * its sync uses, carrier scan-identity policies, and the country a scan's
+ * location names. They change with that app and carry no stability promise;
+ * the tracking contract is the other entry points.
  */
 export * from './core/catalog/parcel.js';
 export * from './core/catalog/hints.js';
 export * from './core/time/result.js';
+export { sameInstantIdentityPolicy, type SameInstantIdentityPolicy } from './core/catalog/eventIdentity.js';
 export { universalCarrierHints } from './providers/shared/hints.js';
 export { recognitionAskedCarriers } from './core/catalog/recognition.js';
 export { countryFlag, countryName, trackingLocationCountry, trackingPlace, type TrackingPlace } from './places/trackingLocation.js';

package/dist/app.js

@@ -1,13 +1,14 @@
 /**
  * Helpers shaped for the parcel app this package was extracted from: its
  * parcel view, carrier-name hints for provider results, the clock helpers
- * its sync uses, and the country a scan's location names. They change with
- * that app and carry no stability promise; the tracking contract is the
- * other entry points.
+ * its sync uses, carrier scan-identity policies, and the country a scan's
+ * location names. They change with that app and carry no stability promise;
+ * the tracking contract is the other entry points.
  */
 export * from './core/catalog/parcel.js';
 export * from './core/catalog/hints.js';
 export * from './core/time/result.js';
+export { sameInstantIdentityPolicy } from './core/catalog/eventIdentity.js';
 export { universalCarrierHints } from './providers/shared/hints.js';
 export { recognitionAskedCarriers } from './core/catalog/recognition.js';
 export { countryFlag, countryName, trackingLocationCountry, trackingPlace } from './places/trackingLocation.js';

package/dist/browser/scraper.js

@@ -7503,7 +7503,8 @@ var Wo = (e) => e.toLowerCase().replace(/[^a-z0-9]/g, ""), Go = [
 	dhlecommerce: "dhl-ecommerce",
 	cainiao: "aliexpress",
 	postnl: "spring-gds",
-	asendiausa: "asendia"
+	asendiausa: "asendia",
+	finlandpost: "posti"
 };
 [
 	...Object.entries(_).filter(([e]) => e !== "unknown").map(([, e]) => Wo(e.displayName)),

package/dist/carriers/dpd/app.d.ts

@@ -0,0 +1,2 @@
+import type { SameInstantIdentityPolicy } from '../../core/catalog/eventIdentity.js';
+export declare const sameInstantIdentityPolicy: SameInstantIdentityPolicy;

package/dist/carriers/dpd/app.js

@@ -0,0 +1,5 @@
+// Verified and postcode-free replies reword the same scans at the same instants.
+// A universal provider can also have stored those scans while DPD was unavailable.
+export const sameInstantIdentityPolicy = {
+    sourceCarrierId: 'dpd', storedSources: ['dpd', 'unknown'], requireProviderCode: false,
+};

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

@@ -5,7 +5,7 @@ import { lookupBudget } from '../../core/adapter/index.js';
 import { ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { eventPoint } from '../../core/result/index.js';
 import { isValidS10TrackingNumber } from '../../core/detection/index.js';
-import { isoTime } from '../../core/time/index.js';
+import { isoTime, mislabeledLocalTime } from '../../core/time/index.js';
 import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 import { classifyIndiaPostEvent } from './status.js';
@@ -87,6 +87,60 @@ function eventText(raw) {
     return EVENT_TEXT[code] ?? code.toLowerCase().split('_')
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 }
+// India Post's code for a flight leaving, in `event_type`. The wording beside
+// it changes: one row read "Aircraft Departure", then "UPLIFT".
+const TAKE_OFF_CODE = 'AircraftTakeOff';
+// The label a take-off's wall clock arrives under; any other offset is kept.
+const UTC_LABEL = /(?:Z|[+-]00:?00)$/i;
+// The zones of the airports a take-off row may name, by IATA code.
+const AIRPORT_ZONES = {
+    BOM: 'Asia/Kolkata', DEL: 'Asia/Kolkata', MAA: 'Asia/Kolkata', CCU: 'Asia/Kolkata',
+    BLR: 'Asia/Kolkata', HYD: 'Asia/Kolkata', COK: 'Asia/Kolkata', AMD: 'Asia/Kolkata',
+    FRA: 'Europe/Berlin', MUC: 'Europe/Berlin', LEJ: 'Europe/Berlin', CGN: 'Europe/Berlin',
+    LHR: 'Europe/London', CDG: 'Europe/Paris', AMS: 'Europe/Amsterdam', ZRH: 'Europe/Zurich',
+    VIE: 'Europe/Vienna', BRU: 'Europe/Brussels', LGG: 'Europe/Brussels', FCO: 'Europe/Rome',
+    MXP: 'Europe/Rome', MAD: 'Europe/Madrid', CPH: 'Europe/Copenhagen', ARN: 'Europe/Stockholm',
+    HEL: 'Europe/Helsinki', IST: 'Europe/Istanbul',
+    DXB: 'Asia/Dubai', AUH: 'Asia/Dubai', DOH: 'Asia/Qatar', SIN: 'Asia/Singapore',
+    HKG: 'Asia/Hong_Kong', BKK: 'Asia/Bangkok', NRT: 'Asia/Tokyo', ICN: 'Asia/Seoul',
+    PVG: 'Asia/Shanghai', KUL: 'Asia/Kuala_Lumpur', CMB: 'Asia/Colombo', DAC: 'Asia/Dhaka',
+    KTM: 'Asia/Kathmandu',
+    JFK: 'America/New_York', EWR: 'America/New_York', ORD: 'America/Chicago',
+    LAX: 'America/Los_Angeles', SFO: 'America/Los_Angeles', YYZ: 'America/Toronto',
+    SYD: 'Australia/Sydney', MEL: 'Australia/Melbourne',
+};
+// Only verified names are expanded; other airport codes stay as the carrier wrote them.
+const AIRPORT_PLACES = {
+    BOM: { name: 'Mumbai Airport', country: 'India' },
+    DEL: { name: 'Delhi Airport', country: 'India' },
+    FRA: { name: 'Frankfurt Airport', country: 'Germany' },
+    CDG: { name: 'Paris Charles de Gaulle Airport', country: 'France' },
+};
+function departureAirport(office) {
+    return /^Office - ([A-Z]{3})\b/.exec(office)?.[1];
+}
+/** Flight remarks have a narrow format; unrelated remarks can contain recipient details. */
+function flightDescription(remarks, office) {
+    const match = /^Flight No:\s*([A-Z0-9]{2}\d{1,4}[A-Z]?)\s*\(From ([A-Z]{3}) To ([A-Z]{3})\)$/.exec(clean(remarks, 500));
+    if (!match || match[2] !== departureAirport(office))
+        return 'Aircraft Departure';
+    const airport = (code) => AIRPORT_PLACES[code] ? `${AIRPORT_PLACES[code].name} (${code})` : code;
+    return `Flight ${match[1]} departed: ${airport(match[2])} → ${airport(match[3])}`;
+}
+/**
+ * The zone a take-off row's clock is kept in. Its `tracked_at` is the
+ * departure airport's wall clock under a UTC label: a take-off was seen
+ * recorded hours before its labelled time. The office names the airport first,
+ * as in "Office - DEL 00000000". Null for every other row, for an airport
+ * outside the table and for a value not labelled UTC: those are read as any
+ * row is.
+ */
+function takeOffZone(providerCode, office, trackedAt) {
+    if (providerCode !== TAKE_OFF_CODE || !UTC_LABEL.test(trackedAt))
+        return null;
+    const airport = departureAirport(office);
+    return airport ? AIRPORT_ZONES[airport] ?? null : null;
+}
 /**
  * The office's point from MySpeedPost's pincode directory. It is looked up by
  * pincode, not by office: "KOLKATA FOREIGN LCAO 900056" comes back as an office
@@ -128,18 +182,24 @@ export function parseIndiaPostTrackingHtml(html, trackingNumber) {
     const parsed = [];
     const seen = new Set();
     events.slice(0, 500).forEach((rawEvent, index) => {
+        const office = clean(rawEvent.office, 120);
+        const providerCode = clean(rawEvent.event_type, 100);
         // tracked_at is ISO; offset-less values are read as Asia/Kolkata, the zone
-        // every India Post office stamps.
-        const time = isoTime(rawEvent.tracked_at, 'Asia/Kolkata', 100);
-        const description = eventText(clean(rawEvent.event));
+        // every India Post office stamps. A take-off is read on its airport's clock.
+        const zone = takeOffZone(providerCode, office, clean(rawEvent.tracked_at, 100));
+        const time = zone
+            ? mislabeledLocalTime(rawEvent.tracked_at, zone, 100)
+            : isoTime(rawEvent.tracked_at, 'Asia/Kolkata', 100);
+        const takeOff = providerCode === TAKE_OFF_CODE;
+        const description = takeOff ? flightDescription(rawEvent.remarks, office) : eventText(clean(rawEvent.event));
         if (!time || !description)
             return;
-        const office = clean(rawEvent.office, 120);
         const pincode = /^\d{6}$/.test(clean(rawEvent.pincode, 6))
             ? clean(rawEvent.pincode, 6)
             : '';
-        const providerCode = clean(rawEvent.event_type, 100);
         const point = officePoint(rawEvent, office);
+        const airportCode = takeOff ? departureAirport(office) : undefined;
+        const airport = airportCode ? AIRPORT_PLACES[airportCode] : undefined;
         const identity = JSON.stringify([time.iso, description, office, pincode, providerCode]);
         if (seen.has(identity))
             return;
@@ -151,7 +211,7 @@ export function parseIndiaPostTrackingHtml(html, trackingNumber) {
             // deliberately never retained.
             event: {
                 time: time.iso,
-                location: [office, pincode].filter(Boolean).join(' '),
+                location: airport ? `${airport.name} (${airportCode}), ${airport.country}` : [office, pincode].filter(Boolean).join(' '),
                 description,
                 stage: classified.stage,
                 ...(providerCode ? { provider_code: providerCode } : {}),

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

@@ -0,0 +1,2 @@
+import type { SameInstantIdentityPolicy } from '../../core/catalog/eventIdentity.js';
+export declare const sameInstantIdentityPolicy: SameInstantIdentityPolicy;

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

@@ -0,0 +1,4 @@
+// MySpeedPost changes a scan's wording while its instant and event_type stay the same.
+export const sameInstantIdentityPolicy = {
+    sourceCarrierId: 'india-post', storedSources: ['india-post'], requireProviderCode: true,
+};

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

@@ -11,6 +11,8 @@ function includesAny(value, candidates) {
  * `in_transit` stage.
  */
 export function classifyIndiaPostEvent(...values) {
+    if (statusKey(values[0]) === 'aircrafttakeoff')
+        return { status: 'in_transit', stage: 'in_transit' };
     const key = values.map(statusKey).filter(Boolean).join(' ');
     if (includesAny(key, [
         'returntosender',

package/dist/carriers/india-post/statuses.json

@@ -1,6 +1,7 @@
 {
   "carrier": "india-post",
   "entries": [
+    { "code": "AircraftTakeOff", "wording": "Aircraft Departure / UPLIFT", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-04", "note": "Departure from the airport named by the office; flight remarks name the route, not a destination arrival." },
     { "code": "ItemBooked", "wording": "Item Booked", "language": "en", "stage": "accepted", "confirmedBy": "fixture", "firstSeen": "2026-09-01", "note": "Substring key `itembooked`; `articlebooked` and `bookingconfirmed` map the same way." },
     { "code": "ItemDispatched", "wording": "Item Dispatched", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-01", "note": "Substring key `itemdispatched`." },
     { "wording": "Item Bagged", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-01", "note": "Substring key `itembagged`." },

package/dist/core/catalog/eventIdentity.d.ts

@@ -0,0 +1,8 @@
+/** Carrier evidence the parcel app uses when updating a stored scan in place. */
+export interface SameInstantIdentityPolicy {
+    readonly sourceCarrierId: string;
+    readonly storedSources: readonly string[];
+    readonly requireProviderCode: boolean;
+}
+/** Unlisted sources cannot identify a reworded scan by its instant alone. */
+export declare function sameInstantIdentityPolicy(sourceCarrierId: string): SameInstantIdentityPolicy | undefined;

package/dist/core/catalog/eventIdentity.js

@@ -0,0 +1,7 @@
+import { sameInstantIdentityPolicy as dpd } from '../../carriers/dpd/app.js';
+import { sameInstantIdentityPolicy as indiaPost } from '../../carriers/india-post/app.js';
+const policies = new Map([dpd, indiaPost].map((policy) => [policy.sourceCarrierId, policy]));
+/** Unlisted sources cannot identify a reworded scan by its instant alone. */
+export function sameInstantIdentityPolicy(sourceCarrierId) {
+    return policies.get(sourceCarrierId);
+}

package/dist/core/catalog/hints.d.ts

@@ -8,9 +8,17 @@ export declare function carrierIdFromName(name: string): string | undefined;
 /**
  * Whether a reported carrier name is already in the catalog: a carrier or alias,
  * another network of a brand that has several ("DHL Express", "GLS Italy"), or
- * one of those followed by a country. Any other name is a carrier new to us.
+ * one of those followed by a country. A name it does not know is a carrier new
+ * to us or a feed (`isCarrierFeedName`).
  */
 export declare function isKnownCarrierName(name: string): boolean;
+/**
+ * Whether a reported name is the postal union's shared feed ("UPU", "Universal
+ * Postal Union"). The feed relays every postal operator's scans and names no
+ * carrier: it has no catalog id and is not a known carrier name, so a reply
+ * that names only the feed says nothing about whose parcel it is.
+ */
+export declare function isCarrierFeedName(name: string): boolean;
 /**
  * The single clock of the country after a known carrier or brand network
  * ("DPD UK", "GLS Italy", "DHL Parcel Netherlands"), for scans that carry no

package/dist/core/catalog/hints.js

@@ -6,11 +6,15 @@ export { carrierBrand };
 const key = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
 // These brands have several regional/service adapters.
 const AMBIGUOUS_BRANDS = ['dhl', 'dpd', 'gls', 'hermes', 'post'];
+// An alias also gives the name its carrier's clock, which moves the stored
+// instants, and so the event ids, of past scans under that name.
 const NAME_ALIASES = {
     ups: 'ups', swisspost: 'swiss-post', laposte: 'la-poste', colissimo: 'la-poste',
     dhlecommerce: 'dhl-ecommerce', cainiao: 'aliexpress', postnl: 'spring-gds',
-    asendiausa: 'asendia',
+    asendiausa: 'asendia', finlandpost: 'posti',
 };
+// The postal union's shared feed, which aggregators list among a parcel's carriers.
+const FEED_NAMES = ['upu', 'universalpostalunion'];
 const CATALOG_NAMES = new Set([
     ...Object.entries(CARRIER_DEFINITIONS).filter(([id]) => id !== 'unknown')
         .map(([, definition]) => key(definition.displayName)),
@@ -81,12 +85,22 @@ export function carrierIdFromName(name) {
 /**
  * Whether a reported carrier name is already in the catalog: a carrier or alias,
  * another network of a brand that has several ("DHL Express", "GLS Italy"), or
- * one of those followed by a country. Any other name is a carrier new to us.
+ * one of those followed by a country. A name it does not know is a carrier new
+ * to us or a feed (`isCarrierFeedName`).
  */
 export function isKnownCarrierName(name) {
     const qualified = countryQualified(name);
     return [key(name), ...(qualified ? [key(qualified.base)] : [])].some((candidate) => CATALOG_NAMES.has(candidate) || NETWORK_BRANDS.some((brand) => candidate.startsWith(brand)));
 }
+/**
+ * Whether a reported name is the postal union's shared feed ("UPU", "Universal
+ * Postal Union"). The feed relays every postal operator's scans and names no
+ * carrier: it has no catalog id and is not a known carrier name, so a reply
+ * that names only the feed says nothing about whose parcel it is.
+ */
+export function isCarrierFeedName(name) {
+    return FEED_NAMES.includes(key(name));
+}
 /**
  * The single clock of the country after a known carrier or brand network
  * ("DPD UK", "GLS Italy", "DHL Parcel Netherlands"), for scans that carry no

package/package.json

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