universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,415 @@
+import { load } from 'cheerio';
+import makeFetchCookie from 'fetch-cookie';
+import { CookieJar } from 'tough-cookie';
+import { ChallengeError, IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { eventPoint } from '../../core/result/index.js';
+import { isValidS10TrackingNumber } from '../../core/detection/index.js';
+import { isoTime } 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';
+// Protocol provenance (inspected 2026-09-01):
+// https://github.com/bivu-m/njs-tracker-scraper
+// MySpeedPost currently exposes its tracking form as a Livewire component at
+// /track and completes the asynchronous lookup through /livewire/update.
+const TRACKING_PAGE = 'https://myspeedpost.com/track';
+const LIVEWIRE_UPDATE = 'https://myspeedpost.com/livewire/update';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_POLL_INTERVAL_MS = 750;
+const DEFAULT_MAX_POLL_ATTEMPTS = 10;
+// MySpeedPost serves its last sync until someone presses Refresh: one parcel
+// kept an 11-day-old "Item Booked" while it reached export customs.
+const REFRESH_AFTER_MS = 30 * 60_000;
+const USER_TIMEZONE = 'Europe/Zurich';
+const MAX_RESPONSE_BYTES = 2_000_000;
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) '
+    + 'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36';
+export { classifyIndiaPostEvent };
+// India Post sends ids and pincodes as numbers as often as strings, so the
+// number-tolerant `cleanScalar` is used throughout instead of `clean`.
+const clean = cleanScalar;
+/** The MySpeedPost session bootstrap ran into Cloudflare, not into a shipment answer. */
+export class IndiaPostChallengeError extends ChallengeError {
+    constructor() {
+        super('India Post', 'India Post tracking returned a browser challenge');
+        this.name = 'IndiaPostChallengeError';
+    }
+}
+export function normalizeIndiaPostTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^[A-Z]{2}\d{9}IN$/.test(value) || !isValidS10TrackingNumber(value)) {
+        throw new TypeError('India Post tracking requires a valid 13-character S10 number ending in IN');
+    }
+    return value;
+}
+export function indiaPostTrackingUrl(raw) {
+    const url = new URL(TRACKING_PAGE);
+    url.searchParams.set('n', normalizeIndiaPostTrackingNumber(raw));
+    url.searchParams.set('sync', 'true');
+    return url.toString();
+}
+function parseTrackingRequest(html) {
+    const $ = load(html);
+    for (const element of $('[tracking-request]').toArray()) {
+        const serialized = $(element).attr('tracking-request');
+        if (!serialized)
+            continue;
+        try {
+            const payload = JSON.parse(serialized);
+            if (isRecord(payload) && Array.isArray(payload.tracking_events))
+                return payload;
+        }
+        catch {
+            // Keep looking in case an unrelated component owns the malformed attribute.
+        }
+    }
+    throw new SchemaError('India Post', 'India Post returned an invalid tracking history');
+}
+// India Post now sends bare codes in `event` (seen 2026-09-22 after a refresh);
+// rows synced earlier carry its prose. Only codes seen live are spelled out.
+const EVENT_TEXT = {
+    ITEM_BOOK: 'Item Booked',
+    BAG_CLOSE: 'Bag Closed',
+    BAG_DISPATCH: 'Bag Dispatched',
+    BAG_FORWARD: 'Bag Forwarded',
+    TMO_RECEIVE: 'Received at Transit Mail Office',
+    ITEM_RECEIVE: 'Item Received',
+    CUSTOM_RECEIVE: 'Item Presented to Customs',
+    CUSTOM_RETURN: 'Item Returned from Customs',
+    TRANSFER_OOE: 'Transferred to Office of Exchange',
+};
+/** Readable text for a code-shaped event such as `BAG_DISPATCH`; prose passes through. */
+function eventText(raw) {
+    if (!/^[A-Za-z]+(?:_[A-Za-z0-9]+)+$/.test(raw))
+        return raw;
+    const code = raw.toUpperCase();
+    return EVENT_TEXT[code] ?? code.toLowerCase().split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+}
+/**
+ * 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
+ * in Delhi. Only a verified entry for the scan's own office is kept.
+ */
+function officePoint(rawEvent, office) {
+    const info = rawEvent.pincode_info;
+    if (!isRecord(info) || info.is_verified !== true)
+        return null;
+    const name = (value) => clean(value, 120).toLocaleUpperCase('en-US').replace(/[^A-Z0-9]+/g, ' ').trim();
+    if (!office || name(info.office_name) !== name(office))
+        return null;
+    const point = eventPoint(info.latitude, info.longitude);
+    // India's mainland and islands; anything else is a bad directory entry.
+    if (!point || point.latitude < 6 || point.latitude > 37 || point.longitude < 68 || point.longitude > 98)
+        return null;
+    return point;
+}
+export function parseIndiaPostTrackingHtml(html, trackingNumber) {
+    const requested = normalizeIndiaPostTrackingNumber(trackingNumber);
+    const $ = load(html);
+    const returned = clean($('#consignment_search').first().attr('value'), 64)
+        .toLocaleUpperCase('en-US')
+        .replace(/[\s.-]/g, '');
+    if (returned !== requested)
+        throw new SchemaError('India Post', 'India Post returned a different shipment');
+    const trackingRequest = parseTrackingRequest(html);
+    if (trackingRequest.tracking_status !== 'Completed') {
+        throw new SchemaError('India Post', 'India Post returned an incomplete tracking response');
+    }
+    if (!Array.isArray(trackingRequest.tracking_events)) {
+        throw new SchemaError('India Post', 'India Post returned invalid tracking events');
+    }
+    const rawEvents = trackingRequest.tracking_events;
+    const events = rawEvents.filter(isRecord);
+    if (events.length !== rawEvents.length || events.length === 0) {
+        throw new SchemaError('India Post', 'India Post returned invalid tracking events');
+    }
+    const parsed = [];
+    const seen = new Set();
+    events.slice(0, 500).forEach((rawEvent, index) => {
+        // 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));
+        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 identity = JSON.stringify([time.iso, description, office, pincode, providerCode]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyIndiaPostEvent(rawEvent.event_type, rawEvent.event, rawEvent.remarks);
+        parsed.push({
+            // Office plus pincode is an operational location. Recipient identity,
+            // contact numbers and address blocks travel on the row and are
+            // deliberately never retained.
+            event: {
+                time: time.iso,
+                location: [office, pincode].filter(Boolean).join(' '),
+                description,
+                stage: classified.stage,
+                ...(providerCode ? { provider_code: providerCode } : {}),
+                ...(point ? { point } : {}),
+            },
+            classified,
+            timestamp: time.timestamp,
+            index,
+        });
+    });
+    parsed.sort((left, right) => right.timestamp - left.timestamp || right.index - left.index);
+    const latest = parsed[0];
+    if (!latest)
+        throw new SchemaError('India Post', 'India Post returned no usable tracking events');
+    const classified = latest.classified.status === 'unknown'
+        ? { status: 'in_transit', stage: 'in_transit' }
+        : latest.classified;
+    const syncedAt = isoTime(trackingRequest.synced_at, 'UTC', 100);
+    return {
+        status: classified.status,
+        current_stage: classified.stage,
+        last_status_text: latest.event.description,
+        last_update: latest.event.time ?? null,
+        expected_delivery: null,
+        timezone: 'Asia/Kolkata',
+        // When MySpeedPost last asked India Post; an old value means stale history.
+        ...(syncedAt ? { source_synced_at: syncedAt.iso } : {}),
+        events: parsed.slice(0, 100).map((item) => item.event),
+    };
+}
+function enumValue(value) {
+    return Array.isArray(value) && typeof value[0] === 'string' ? value[0] : '';
+}
+function parseTrackSnapshot(snapshot, trackingNumber) {
+    let parsed;
+    try {
+        parsed = JSON.parse(snapshot);
+    }
+    catch (error) {
+        throw new SchemaError('India Post', 'India Post returned invalid Livewire state', { cause: error });
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.data) || !isRecord(parsed.memo)
+        || parsed.memo.name !== 'track-consignment') {
+        throw new SchemaError('India Post', 'India Post returned invalid Livewire state');
+    }
+    const returned = clean(parsed.data.consignment_number, 64)
+        .toLocaleUpperCase('en-US')
+        .replace(/[\s.-]/g, '');
+    if (returned !== trackingNumber)
+        throw new SchemaError('India Post', 'India Post returned a different shipment');
+    const status = enumValue(parsed.data.status);
+    if (!status)
+        throw new SchemaError('India Post', 'India Post returned an invalid tracking status');
+    return { snapshot, data: parsed.data, status };
+}
+function initialTrackComponent(html, trackingNumber) {
+    const $ = load(html);
+    for (const element of $('[wire\\:snapshot]').toArray()) {
+        const snapshot = $(element).attr('wire:snapshot');
+        if (!snapshot)
+            continue;
+        try {
+            const parsed = JSON.parse(snapshot);
+            if (isRecord(parsed) && isRecord(parsed.memo) && parsed.memo.name === 'track-consignment') {
+                return parseTrackSnapshot(snapshot, trackingNumber);
+            }
+        }
+        catch {
+            // A page can contain several unrelated Livewire components.
+        }
+    }
+    throw new SchemaError('India Post', 'India Post did not return its tracking component');
+}
+function csrfToken(html) {
+    const token = clean(load(html)('meta[name="csrf-token"]').attr('content'), 512);
+    if (!/^[A-Za-z0-9_-]{20,512}$/.test(token)) {
+        throw new SchemaError('India Post', 'India Post did not issue a tracking session token');
+    }
+    return token;
+}
+function parseLivewireUpdate(payload, trackingNumber) {
+    if (!isRecord(payload) || !Array.isArray(payload.components) || payload.components.length !== 1
+        || !isRecord(payload.components[0])) {
+        throw new SchemaError('India Post', 'India Post returned an invalid Livewire response');
+    }
+    const rawComponent = payload.components[0];
+    if (typeof rawComponent.snapshot !== 'string') {
+        throw new SchemaError('India Post', 'India Post returned an invalid Livewire response');
+    }
+    return {
+        component: parseTrackSnapshot(rawComponent.snapshot, trackingNumber),
+        effects: isRecord(rawComponent.effects) ? rawComponent.effects : {},
+    };
+}
+function dispatchNames(effects) {
+    if (!Array.isArray(effects.dispatches))
+        return new Set();
+    return new Set(effects.dispatches
+        .filter(isRecord)
+        .map((dispatch) => clean(dispatch.name, 100))
+        .filter(Boolean));
+}
+// Since 2026-09-24 Cloudflare also injects its passive detection loader
+// (/cdn-cgi/challenge-platform/scripts/jsd/main.js) into ordinary answers, so
+// only the interstitial's own markers count as a challenge.
+function challengePage(status, html, headers) {
+    return [401, 403, 419, 429].includes(status)
+        || headers.get('cf-mitigated') === 'challenge'
+        || /Just a moment|Enable JavaScript and cookies|cf-chl-|_cf_chl_opt/i.test(html);
+}
+function pause(milliseconds) {
+    return milliseconds > 0
+        ? new Promise((resolve) => setTimeout(resolve, milliseconds))
+        : Promise.resolve();
+}
+export class IndiaPostTracker {
+    timeoutMs;
+    pollIntervalMs;
+    maxPollAttempts;
+    fetcher;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date());
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.maxPollAttempts = options.maxPollAttempts ?? DEFAULT_MAX_POLL_ATTEMPTS;
+        this.fetcher = options.fetcher ?? fetch;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('India Post timeout must be positive');
+        }
+        if (!Number.isFinite(this.pollIntervalMs) || this.pollIntervalMs < 0) {
+            throw new TypeError('India Post poll interval cannot be negative');
+        }
+        if (!Number.isInteger(this.maxPollAttempts) || this.maxPollAttempts < 1) {
+            throw new TypeError('India Post poll attempts must be positive');
+        }
+    }
+    async request(fetcher, url, init) {
+        const result = await fetchBounded(url, init, {
+            provider: 'India Post tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            redirect: 'manual',
+            fetcher,
+            allowHttpError: true,
+        });
+        const html = decodeText(result.bytes);
+        if (challengePage(result.response.status, html, result.response.headers)) {
+            throw new IndiaPostChallengeError();
+        }
+        if (!result.response.ok) {
+            throw new UpstreamHttpError('India Post tracking', result.response.status);
+        }
+        return { bytes: result.bytes, html };
+    }
+    async update(fetcher, trackingNumber, pageUrl, token, snapshot, calls, updates = {}) {
+        const result = await this.request(fetcher, LIVEWIRE_UPDATE, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Accept-Language': 'en-US,en;q=0.9',
+                'Content-Type': 'application/json',
+                Origin: 'https://myspeedpost.com',
+                Referer: pageUrl,
+                'User-Agent': USER_AGENT,
+                'X-Livewire': '',
+            },
+            body: JSON.stringify({
+                _token: token,
+                components: [{ snapshot, updates, calls }],
+            }),
+        });
+        return parseLivewireUpdate(parseJsonBytes(result.bytes, 'India Post tracking'), trackingNumber);
+    }
+    async fetch(trackingNumber) {
+        const normalized = normalizeIndiaPostTrackingNumber(trackingNumber);
+        const pageUrl = indiaPostTrackingUrl(normalized);
+        // The Livewire flow is stateful: the session cookie issued with the page
+        // must travel with every /livewire/update call, so the jar is per lookup.
+        const fetcher = makeFetchCookie(this.fetcher, new CookieJar());
+        const page = await this.request(fetcher, pageUrl, {
+            headers: {
+                Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Accept-Language': 'en-US,en;q=0.9',
+                'User-Agent': USER_AGENT,
+            },
+        });
+        const initial = initialTrackComponent(page.html, normalized);
+        if (initial.status === 'Completed') {
+            const cached = parseIndiaPostTrackingHtml(page.html, normalized);
+            const syncedAt = Date.parse(String(cached.source_synced_at ?? ''));
+            if (Number.isFinite(syncedAt) && this.now().getTime() - syncedAt < REFRESH_AFTER_MS)
+                return cached;
+            // What the page's Refresh button sends. A failed refresh still leaves
+            // the cached history, which is better than no answer.
+            try {
+                return await this.complete(fetcher, normalized, pageUrl, csrfToken(page.html), initial.snapshot, [{
+                        path: '',
+                        method: '__dispatch',
+                        params: ['refresh_consignment', { userTimezone: USER_TIMEZONE }],
+                    }], { userTimezone: USER_TIMEZONE });
+            }
+            catch {
+                return cached;
+            }
+        }
+        if (!['New', 'Processing'].includes(initial.status)) {
+            throw new SchemaError('India Post', 'India Post returned an unsupported tracking state');
+        }
+        const token = csrfToken(page.html);
+        return initial.status === 'Processing'
+            ? this.complete(fetcher, normalized, pageUrl, token, initial.snapshot, [{
+                    path: '',
+                    method: 'fetchStatus',
+                    params: [],
+                }])
+            : this.complete(fetcher, normalized, pageUrl, token, initial.snapshot, [{
+                    path: '',
+                    method: '__dispatch',
+                    params: ['set_consignment_number', { consignment_number: normalized }],
+                }, {
+                    path: '',
+                    method: 'submit',
+                    params: [USER_TIMEZONE],
+                }], { userTimezone: USER_TIMEZONE });
+    }
+    /** Send the first calls, then poll `fetchStatus` until the component completes. */
+    async complete(fetcher, normalized, pageUrl, token, snapshot, calls, updates = {}) {
+        let update = await this.update(fetcher, normalized, pageUrl, token, snapshot, calls, updates);
+        for (let attempt = 0; attempt <= this.maxPollAttempts; attempt += 1) {
+            const names = dispatchNames(update.effects);
+            if (names.has('consignment_not_found'))
+                throw new NotFoundError('India Post');
+            if (update.component.status === 'Completed') {
+                const html = typeof update.effects.html === 'string' ? update.effects.html : '';
+                if (!html)
+                    throw new SchemaError('India Post', 'India Post returned an empty completed response');
+                return parseIndiaPostTrackingHtml(html, normalized);
+            }
+            if (update.component.status !== 'Processing') {
+                throw new SchemaError('India Post', 'India Post returned an unsupported tracking state');
+            }
+            if (attempt === this.maxPollAttempts)
+                break;
+            await pause(this.pollIntervalMs);
+            update = await this.update(fetcher, normalized, pageUrl, token, update.component.snapshot, [{ path: '', method: 'fetchStatus', params: [] }]);
+        }
+        // The backend kept saying "Processing": it answered, but it proved nothing
+        // about the shipment, so this must not become a not-found cooldown.
+        throw new IndeterminateError('India Post', 'India Post tracking did not complete in time');
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new IndiaPostTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'india-post',
+        // The Livewire submit-and-poll cycle is part of the direct call: it is one
+        // stateful conversation with one host, not a fallback tier.
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

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

@@ -0,0 +1,74 @@
+{
+  "id": "india-post",
+  "displayName": "India Post",
+  "aliases": [
+    "Speed Post",
+    "India Post Speed Post",
+    "Department of Posts"
+  ],
+  "region": {
+    "countries": [
+      "IN"
+    ]
+  },
+  "brand": {
+    "color": "#b82025"
+  },
+  "selectable": true,
+  "timezone": "Asia/Kolkata",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "india-post",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://myspeedpost.com/track?n={trackingNumber}&sync=true",
+    "canaryUrl": "https://myspeedpost.com/track",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "myspeedpost.com"
+      ],
+      "params": [
+        "n"
+      ],
+      "path": "^/s/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "india-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}IN$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

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

@@ -0,0 +1,58 @@
+{
+  "carrier": "india-post",
+  "records": [
+    {
+      "number": "ED415656540IN",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "india-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "JN067614884IN",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "india-post",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "JN067614885IN",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Invented placeholder used as a shape check. Filed under India Post, which no rule claims."
+    },
+    {
+      "number": "RR000000005IN",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "india-post",
+        "confidence": "high"
+      },
+      "note": "Invented S10 identifier with a valid check digit."
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+/**
+ * India Post status vocabulary.
+ *
+ * The tracking rows carry no stable status code: `event_type`, `event` and
+ * `remarks` are all English prose that India Post words differently per office.
+ * So this classifier normalizes the three of them into one alphanumeric key and
+ * matches substrings, most specific first — returns and failures before
+ * deliveries, deliveries before pickups, pickups before generic movement.
+ *
+ * The fallback is `{ status: 'unknown', stage: 'in_transit' }`: every row here
+ * is a physical scan, so "something moved" is the safe reading, while the
+ * `unknown` status lets the caller see that nothing was actually recognized.
+ *
+ * Provenance: the MySpeedPost Livewire tracker inspected 2026-09-01, with
+ * https://github.com/bivu-m/njs-tracker-scraper as the starting point.
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/**
+ * Classify one row from its `event_type`, `event` and `remarks`. Never
+ * undefined: an unrecognized row falls back to an `unknown` status on an
+ * `in_transit` stage.
+ */
+export declare function classifyIndiaPostEvent(...values: unknown[]): ClassifiedStatus;

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

@@ -0,0 +1,99 @@
+import { cleanScalar } from '../../core/transport/index.js';
+function statusKey(value) {
+    return cleanScalar(value, 200).toLocaleLowerCase('en-US').replace(/[^a-z0-9]+/g, '');
+}
+function includesAny(value, candidates) {
+    return candidates.some((candidate) => value.includes(candidate));
+}
+/**
+ * Classify one row from its `event_type`, `event` and `remarks`. Never
+ * undefined: an unrecognized row falls back to an `unknown` status on an
+ * `in_transit` stage.
+ */
+export function classifyIndiaPostEvent(...values) {
+    const key = values.map(statusKey).filter(Boolean).join(' ');
+    if (includesAny(key, [
+        'returntosender',
+        'returnedtocustomer',
+        'returnedtobookingoffice',
+        'returnitem',
+    ]))
+        return { status: 'exception', stage: 'returned' };
+    if (includesAny(key, [
+        'insufficientaddress',
+        'addresseecannotbelocated',
+        'damaged',
+        'refused',
+        'lost',
+    ]))
+        return { status: 'exception', stage: 'exception' };
+    if (includesAny(key, [
+        'deliveryattempted',
+        'deliveryfailed',
+        'notdelivered',
+        'undelivered',
+    ]))
+        return { status: 'exception', stage: 'failed_attempt' };
+    if (includesAny(key, [
+        'itemdelivered',
+        'deliveredtorecipient',
+        'delivereddelivery',
+    ]))
+        return { status: 'delivered', stage: 'delivered' };
+    if (includesAny(key, [
+        'readyforpickup',
+        'readyforcollection',
+        'awaitingcollection',
+    ]))
+        return { status: 'out_for_delivery', stage: 'ready_for_pickup' };
+    if (includesAny(key, [
+        'outfordelivery',
+        'itemoutfordelivery',
+        'sentfordelivery',
+    ]))
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    // Customs handing the item back (CUSTOM_RETURN, "returned from export
+    // Customs/Security", "released by export Customs") ends the customs step.
+    if (includesAny(key, [
+        'customreturn',
+        'returnedfromexportcustoms',
+        'returnedfromcustoms',
+        'releasedbyexportcustoms',
+        'releasedbycustoms',
+    ]))
+        return { status: 'in_transit', stage: 'in_transit' };
+    if (includesAny(key, ['customs', 'customclearance', 'customreceive'])) {
+        return { status: 'in_transit', stage: 'customs' };
+    }
+    if (includesAny(key, ['itembook', 'articlebooked', 'bookingconfirmed'])) {
+        return { status: 'pending', stage: 'accepted' };
+    }
+    if (includesAny(key, [
+        'shipmentinformationreceived',
+        'labelcreated',
+        'articlecreated',
+        'consignmentcreated',
+    ]))
+        return { status: 'pending', stage: 'registered' };
+    if (includesAny(key, [
+        'itembagged',
+        'itemdispatched',
+        'itemreceived',
+        'receivedat',
+        'departed',
+        'arrived',
+        'forwarded',
+        'intransit',
+        'handedover',
+        // Codes India Post sends since 2026-09 (BAG_DISPATCH, TRANSFER_OOE...).
+        'inducted',
+        'bagclose',
+        'bagdispatch',
+        'bagforward',
+        'tmoreceive',
+        'itemreceive',
+        'transferooe',
+    ]))
+        return { status: 'in_transit', stage: 'in_transit' };
+    return { status: 'unknown', stage: 'in_transit' };
+}