universal-parcel-scraper 0.13.1 → 0.14.0-main.340

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **98 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **99 dedicated adapters** and **5 universal fallbacks**
 
 <sub>119 catalog entries · 58 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -33,9 +33,9 @@ its own as a command, a Node library or an HTTP server.
 ## Benchmark
 
 <!-- GENERATED:coverage -->
-In a curated benchmark of 113 carriers, dedicated adapters return tracking history for **71**, rising to **84** with all fallbacks enabled. The best single aggregator returns 53.
+In a curated benchmark of 113 carriers, dedicated adapters return tracking history for **72**, rising to **84** with all fallbacks enabled. The best single aggregator returns 53.
 
-<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 84, This project, dedicated adapters alone 71, ParcelsApp 53, Postal Ninja 43, 17TRACK 40, Ship24 42, UPU 12." width="760">
+<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 84, This project, dedicated adapters alone 72, ParcelsApp 53, Postal Ninja 43, 17TRACK 40, Ship24 42, UPU 12." width="760">
 <!-- /GENERATED:coverage -->
 
 [Method and results per carrier](providers/COVERAGE.md)

package/data/catalog.json

@@ -1741,7 +1741,7 @@
     "timezone": "UTC",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "royal-mail"
     },
     "canaryUrl": "https://www.royalmail.com/track-your-item",
     "trackingUrlTemplate": "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",

package/data/coverage-summary.json

@@ -1,11 +1,11 @@
 {
   "catalog": 119,
-  "activeAdapters": 98,
+  "activeAdapters": 99,
   "countries": 58,
   "referenceCarriers": 113,
   "comparison": {
     "combined": 84,
-    "direct": 71,
+    "direct": 72,
     "providers": {
       "ParcelsApp": 53,
       "Postal Ninja": 43,

package/dist/browser/scraper.js

@@ -1407,7 +1407,7 @@ var ce = {
 		timezone: "UTC",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "royal-mail"
 		},
 		canaryUrl: "https://www.royalmail.com/track-your-item",
 		trackingUrlTemplate: "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",
@@ -8281,8 +8281,8 @@ var gs = { carriers: [
 	},
 	{
 		carrier: "royal-mail",
-		direct: "Disabled",
-		sample: "Error",
+		direct: "Yes (local Chromium)",
+		sample: "✓ 8",
 		references: [{ results: {
 			Ship24: "no_history",
 			ParcelsApp: 1,
@@ -8290,7 +8290,7 @@ var gs = { carriers: [
 			"Postal Ninja": 4,
 			UPU: "no_history"
 		} }, {
-			note: "Alternate public reference returned eight identity-bound full-history scans in an interactive official session. Fresh automated Chromium obtained the matching microsummary, but its separate events request failed; automated full history remains unverified: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/",
+			note: "Public references returned eight and six identity-bound history scans in fresh automated Chromium on both local and Linux server hosts: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/ and https://www.reddit.com/r/Sugargoo/comments/1we8q17/where_is_my_parcel/. The official documentation example returned E1142, which remains inconclusive. Anonymous requests can still stall before the API request or be reset; browser and runtime compatibility matter. TRAWL deployment compatibility is unverified.",
 			results: {}
 		}]
 	},

package/dist/carriers/royal-mail/adapter.d.ts

@@ -2,19 +2,10 @@ import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.j
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
 import { TrawlClient } from '../../core/transport/index.js';
-export declare function normalizeRoyalMailNumber(raw: string): string;
-export declare function royalMailTrackingUrl(trackingNumber: string): string;
-export declare function royalMailSummaryApiUrl(trackingNumber: string): string;
-export declare function royalMailEventsApiUrl(trackingNumber: string): string;
-/** Only the field vocabulary consumed by the public tracking application. */
-export declare function parseRoyalMailTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
-/**
- * The page the browser rendered, read only to tell a bot challenge from an
- * inconclusive load. Rendered text never decides not-found: only the
- * structured reply does.
- */
-export declare function parseRoyalMailTrackingHtml(page: string): 'challenged' | 'inconclusive';
+export { normalizeRoyalMailNumber, parseRoyalMailTrackingHtml, parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
 export interface RoyalMailTrackerOptions {
+    /** Fresh local Chromium; preferred when supplied. */
+    executablePath?: string | null;
     timeoutMs?: number;
     /** Legacy configuration seam; `trawl` is preferred. */
     trawlUrl?: string;

package/dist/carriers/royal-mail/adapter.js

@@ -1,151 +1,15 @@
-import { DateTime } from 'luxon';
-import { load } from 'cheerio';
-import { ChallengeError, IndeterminateError, InvalidInputError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { ChallengeError, IndeterminateError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
-import { clean, cleanScalar, TRAWL_TRANSPORT_ALLOWANCE_MS, TrawlClient } from '../../core/transport/index.js';
-import { explicitOffsetTime } from '../../core/time/index.js';
+import { cleanScalar, TRAWL_TRANSPORT_ALLOWANCE_MS, TrawlClient } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
-import { royalMailEventStage, royalMailStage, royalMailSummaryStage, statusForStage } from './status.js';
-/** Read the response produced by Royal Mail's form and hCaptcha callback. */
-const TRACKING_BASE = 'https://www.royalmail.com/track-your-item';
-const SUMMARY_API_PREFIX = 'https://api-web.royalmail.com/mailpieces/microsummary/v1/summary/';
-const EVENTS_API_PREFIX = 'https://api-web.royalmail.com/mailpieces/v3/';
+import { fetchRoyalMailInBrowser } from './browser.js';
+import { normalizeRoyalMailNumber, parseRoyalMailTrackingHtml, parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
+export { normalizeRoyalMailNumber, parseRoyalMailTrackingHtml, parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
 const MAX_BYTES = 10_000_000;
 const DEFAULT_TIMEOUT_MS = 60_000;
-// How long the browser may wait for the page's own summary call after the page settles.
 const SETTLE_TIMEOUT_MS = 15_000;
-// Captured replies beyond this many are noise, never the answer.
 const MAX_CAPTURED = 20;
-const MAX_EVENTS_TO_INSPECT = 500;
-const MAX_EVENTS_TO_RETURN = 100;
-export function normalizeRoyalMailNumber(raw) {
-    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
-    if (!/^[A-Z]{2}\d{9}GB$/.test(value)) {
-        throw new InvalidInputError('Royal Mail', 'Royal Mail tracking numbers must match the UPU S10 format');
-    }
-    return value;
-}
-export function royalMailTrackingUrl(trackingNumber) {
-    return `${TRACKING_BASE}#/tracking-results/${normalizeRoyalMailNumber(trackingNumber)}`;
-}
-export function royalMailSummaryApiUrl(trackingNumber) {
-    return `${SUMMARY_API_PREFIX}${normalizeRoyalMailNumber(trackingNumber)}`;
-}
-export function royalMailEventsApiUrl(trackingNumber) {
-    return `${EVENTS_API_PREFIX}${normalizeRoyalMailNumber(trackingNumber)}/events`;
-}
-/** Preserve offset-free wall time instead of assigning a zone to overseas scans. */
-function eventTime(value) {
-    const raw = cleanScalar(value, 64);
-    // A date or wall clock must never acquire the carrier's default timezone.
-    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-](?:(?:0\d|1[0-3]):?[0-5]\d|14:?00))$/i.test(raw))
-        return null;
-    return explicitOffsetTime(raw)?.iso ?? null;
-}
-/** A delivery estimate reduced to its calendar day. */
-function expectedDelivery(value) {
-    const raw = cleanScalar(value, 64);
-    const day = /^\d{4}-\d{2}-\d{2}/.exec(raw)?.[0];
-    return day && DateTime.fromISO(day).isValid ? day : null;
-}
-/** Only the field vocabulary consumed by the public tracking application. */
-export function parseRoyalMailTrackingResponse(payload, trackingNumber) {
-    const number = normalizeRoyalMailNumber(trackingNumber);
-    if (!isRecord(payload))
-        throw new SchemaError('Royal Mail', 'Royal Mail returned an invalid tracking response');
-    const errors = Array.isArray(payload.errors) ? payload.errors.filter(isRecord) : [];
-    if (errors.some(error => error.errorCode === 'E0015' || error.code === 'E0015')) {
-        throw new ChallengeError('Royal Mail', 'Royal Mail denied the tracking session');
-    }
-    if (String(payload.httpCode) === '429')
-        throw new RateLimitedError('Royal Mail');
-    if (errors.length)
-        throw new IndeterminateError('Royal Mail', 'Royal Mail could not confirm the tracking status');
-    const mailpiece = payload.mailPieces;
-    // Both summary and events endpoints return one object, not the array used by the
-    // recent-items endpoint. Never treat a gateway 404 or schema drift as not-found.
-    if (!isRecord(mailpiece) || !isRecord(mailpiece.summary)) {
-        throw new SchemaError('Royal Mail', 'Royal Mail returned an invalid tracking response');
-    }
-    if (cleanScalar(mailpiece.mailPieceId).toUpperCase() !== number) {
-        throw new SchemaError('Royal Mail', 'Royal Mail did not return the requested parcel');
-    }
-    const summary = mailpiece.summary;
-    const summaryText = cleanScalar(summary.statusDescription);
-    if (mailpiece.events !== undefined && !Array.isArray(mailpiece.events)) {
-        throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
-    }
-    const scans = Array.isArray(mailpiece.events) ? mailpiece.events : [];
-    const events = [];
-    const seen = new Set();
-    for (const raw of scans.slice(0, MAX_EVENTS_TO_INSPECT)) {
-        if (!isRecord(raw))
-            throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
-        // The website returns Markdown emphasis, including "**Delivered by**".
-        // Normalize it before classification so delivery prose is still redacted.
-        const description = cleanScalar(raw.eventName).replace(/\*\*/g, '').trim();
-        if (!description)
-            throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
-        const code = cleanScalar(raw.eventCode, 64);
-        const mapped = royalMailEventStage(code);
-        const stage = mapped ?? royalMailStage(description) ?? undefined;
-        const time = eventTime(raw.eventDateTime);
-        const timeText = cleanScalar(raw.eventDateTime, 64);
-        const location = cleanScalar(raw.locationName, 250);
-        const event = {
-            ...(time ? { time } : {}),
-            ...(!time && timeText ? { provider_time_text: timeText } : {}),
-            ...(location ? { location } : {}),
-            description: stage === 'delivered' ? 'Delivered' : description,
-            ...(stage ? { stage } : {}),
-            ...(mapped ? { stage_source: 'carrier_map' } : {}),
-            ...(/^[A-Za-z0-9_-]+$/.test(code) ? { provider_code: code } : {}),
-        };
-        const identity = JSON.stringify([time ?? timeText, location, event.description]);
-        if (seen.has(identity))
-            continue;
-        seen.add(identity);
-        events.push(event);
-    }
-    // Royal Mail also sorts the history; upstream order is not guaranteed.
-    // A partial comparator can move resolved scans across unresolved overseas
-    // clocks. Preserve provider order unless every scan denotes an instant.
-    if (events.every(event => event.time)) {
-        events.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
-    }
-    const trimmed = events.slice(0, MAX_EVENTS_TO_RETURN);
-    const summaryCategory = cleanScalar(summary.statusCategory);
-    const statusText = summaryText || summaryCategory || trimmed[0]?.description;
-    if (!statusText)
-        throw new SchemaError('Royal Mail', 'Royal Mail returned no usable tracking status');
-    const stage = royalMailSummaryStage(summaryCategory, statusText) ?? undefined;
-    const delivered = stage === 'delivered';
-    return {
-        status: stage ? statusForStage(stage) : 'unknown',
-        ...(stage ? { current_stage: stage } : {}),
-        last_status_text: delivered ? 'Delivered' : statusText,
-        last_update: eventTime(summary.lastEventDateTime) || trimmed[0]?.time || null,
-        expected_delivery: delivered || !isRecord(mailpiece.estimatedDelivery)
-            ? null : expectedDelivery(mailpiece.estimatedDelivery.date),
-        events: trimmed,
-        ...(trimmed.length ? {} : { summary_only: true }),
-    };
-}
-/**
- * The page the browser rendered, read only to tell a bot challenge from an
- * inconclusive load. Rendered text never decides not-found: only the
- * structured reply does.
- */
-export function parseRoyalMailTrackingHtml(page) {
-    const $ = load(page);
-    $('script, style, noscript').remove();
-    const visible = clean($('body').text(), 20_000);
-    if (/access denied|just a moment|attention required|are you a robot|verify you are human|before you proceed|unusual traffic/i.test(visible)) {
-        return 'challenged';
-    }
-    return 'inconclusive';
-}
 export class RoyalMailTracker {
     timeoutMs;
     trawlUrl;
@@ -153,6 +17,7 @@ export class RoyalMailTracker {
     #fetcher;
     #recorder;
     #fullHistory;
+    #executablePath;
     constructor(options = {}) {
         if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
             throw new TypeError('Royal Mail timeout must be positive');
@@ -163,6 +28,7 @@ export class RoyalMailTracker {
         this.#fetcher = options.fetcher;
         this.#recorder = options.recorder ?? NOOP_RECORDER;
         this.#fullHistory = options.fullHistory ?? false;
+        this.#executablePath = options.executablePath ?? null;
     }
     /** The injected browser service, or one built from the configured URL. */
     #browserService() {
@@ -172,8 +38,11 @@ export class RoyalMailTracker {
     }
     async fetch(trackingNumber, context = {}) {
         const number = normalizeRoyalMailNumber(trackingNumber);
-        // Akamai refuses every non-browser client, so a direct attempt only burns
-        // time. There is one step, and it is the browser.
+        if (this.#executablePath) {
+            return runSteps({ carrier: 'royal-mail', budgetMs: context.budgetMs ?? this.timeoutMs,
+                signal: context.signal, recorder: this.#recorder }, [{ id: 'browser', run: ({ remainingMs, signal }) => fetchRoyalMailInBrowser(number, this.#executablePath, signal, Math.min(60_000, remainingMs), this.#fullHistory) }]);
+        }
+        // The legacy service remains available through explicit tracker instances.
         const trawl = this.#browserService();
         if (!trawl) {
             throw new ChallengeError('Royal Mail', 'Royal Mail challenged direct tracking; configure FLARESOLVERR_URL for browser fallback');
@@ -241,6 +110,8 @@ export class RoyalMailTracker {
                         throw new IndeterminateError('Royal Mail', 'Royal Mail could not confirm the tracking status');
                     }
                 }
+                if ([404, 410].includes(entry.status))
+                    throw new TransportError('Royal Mail', 'Royal Mail tracking endpoint is unavailable');
                 if (entry.status >= 400)
                     throw new UpstreamHttpError('Royal Mail', entry.status);
                 if (entry.status !== 200 || entry.truncated || entry.base64Encoded || entry.error || entry.body === null)
@@ -279,7 +150,7 @@ export class RoyalMailTracker {
                 const summaryPiece = summaryPayload.mailPieces;
                 return this.#structuredResult(number, { mailPieces: {
                         mailPieceId: number, summary: summaryPiece.summary,
-                        estimatedDelivery: summaryPiece.estimatedDelivery, events: historyPiece.events,
+                        estimatedDelivery: historyPiece.estimatedDelivery ?? summaryPiece.estimatedDelivery, events: historyPiece.events,
                     } });
             }
         }
@@ -295,17 +166,16 @@ export class RoyalMailTracker {
         return result;
     }
 }
-export const adapter = (environment) => {
-    const tracker = new RoyalMailTracker({
-        fetcher: environment.fetcher,
-        trawl: environment.trawl,
-        recorder: environment.recorder,
-        fullHistory: true,
-    });
+export const adapter = environment => {
+    const tracker = new RoyalMailTracker({ executablePath: environment.browserExecutablePath,
+        recorder: environment.recorder, fullHistory: true });
     return {
-        id: 'royal-mail', recordsSteps: true,
-        // Akamai refuses every non-browser client, so there is no direct tier.
-        steps: ['trawl'],
-        track: (input, context) => tracker.fetch(input.number, context),
+        id: 'royal-mail', recordsSteps: true, steps: ['browser'],
+        track: (input, context) => {
+            normalizeRoyalMailNumber(input.number);
+            if (!environment.browserExecutablePath)
+                throw new ChallengeError('Royal Mail', 'Royal Mail requires TRACKING_CHROMIUM_PATH');
+            return tracker.fetch(input.number, context);
+        },
     };
 };

package/dist/carriers/royal-mail/browser.d.ts

@@ -0,0 +1,5 @@
+import type { Page } from 'playwright-core';
+import type { CarrierResult } from '../../core/result/index.js';
+/** Observe the application's request; its issued session stays in the browser. */
+export declare function captureRoyalMailReply(page: Page, url: string, number: string, phase: 'summary' | 'events', signal: AbortSignal, timeoutMs: number, trigger: () => Promise<void>): Promise<Record<string, unknown>>;
+export declare function fetchRoyalMailInBrowser(number: string, executablePath: string, signal: AbortSignal, timeoutMs: number, fullHistory: boolean): Promise<CarrierResult>;

package/dist/carriers/royal-mail/browser.js

@@ -0,0 +1,198 @@
+import { carrierErrorKind, ChallengeError, IndeterminateError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { withLocalBrowser } from '../../core/transport/localBrowser.js';
+import { isRecord } from '../../core/types.js';
+import { parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
+const PROVIDER = 'Royal Mail';
+const ORIGIN = 'https://www.royalmail.com';
+const MAX_BYTES = 2_000_000;
+/** Observe the application's request; its issued session stays in the browser. */
+export async function captureRoyalMailReply(page, url, number, phase, signal, timeoutMs, trigger) {
+    const deadline = AbortSignal.any([signal, AbortSignal.timeout(Math.max(1, Math.floor(timeoutMs)))]);
+    deadline.throwIfAborted();
+    let active = true;
+    let refresh = false;
+    let bytes = 0;
+    let count = 0;
+    let resolve;
+    let reject;
+    const reply = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void reply.catch(() => { });
+    const matches = (request) => active && request.url() === url && request.method() === 'GET'
+        && ['xhr', 'fetch'].includes(request.resourceType()) && request.frame() === page.mainFrame();
+    const failed = (request) => { if (matches(request))
+        reject(new TransportError(PROVIDER, 'Royal Mail tracking request failed')); };
+    const aborted = () => reject(signal.aborted ? signal.reason : new TransportError(PROVIDER, 'Royal Mail tracking response timed out'));
+    const received = (response) => {
+        if (!matches(response.request()))
+            return;
+        void (async () => {
+            if (++count > 3)
+                throw new SchemaError(PROVIDER, 'Royal Mail returned too many tracking replies');
+            const status = response.status();
+            const headers = response.headers();
+            if (status === 429) {
+                const retry = headers['retry-after'];
+                throw new RateLimitedError(PROVIDER, retry && /^\d+$/.test(retry) ? Number(retry) * 1000 : undefined);
+            }
+            if (status === 403)
+                throw new ChallengeError(PROVIDER);
+            if (status === 410)
+                throw new TransportError(PROVIDER, 'Royal Mail tracking endpoint is unavailable');
+            if (![200, 401, 404].includes(status))
+                throw new UpstreamHttpError(PROVIDER, status);
+            const invalid = () => status === 401 ? new ChallengeError(PROVIDER)
+                : status === 404 ? new TransportError(PROVIDER, 'Royal Mail tracking endpoint is unavailable') : new SchemaError(PROVIDER);
+            const length = headers['content-length'] === undefined ? 0 : Number(headers['content-length']);
+            if (!(headers['content-type'] ?? '').includes('application/json') || !Number.isSafeInteger(length)
+                || length < 0 || length > MAX_BYTES)
+                throw invalid();
+            // The page already buffers its XHR. Bound both the declared and decoded
+            // capture, plus repeated replies, before parsing anything for the result.
+            const body = await response.body();
+            if (!active)
+                return;
+            bytes += body.byteLength;
+            if (body.byteLength > MAX_BYTES || bytes > 2 * MAX_BYTES)
+                throw new SchemaError(PROVIDER);
+            let data;
+            try {
+                data = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                throw invalid();
+            }
+            if (!isRecord(data))
+                throw new SchemaError(PROVIDER);
+            const errors = Array.isArray(data.errors) ? data.errors.filter(isRecord) : [];
+            const denied = errors.some(error => error.errorCode === 'E0015' || error.code === 'E0015');
+            if (status === 401 && denied && !refresh) {
+                refresh = true;
+                return;
+            }
+            if (status === 401 || denied)
+                throw new ChallengeError(PROVIDER);
+            if (errors.some(error => error.errorCode === 'E1142' || error.code === 'E1142')) {
+                throw new IndeterminateError(PROVIDER, 'Royal Mail could not confirm the tracking status');
+            }
+            if (status === 404)
+                throw new TransportError(PROVIDER, 'Royal Mail tracking endpoint is unavailable');
+            if (status !== 200)
+                throw new UpstreamHttpError(PROVIDER, status);
+            if (data.errors !== undefined || data.error !== undefined || data.httpCode !== undefined)
+                throw new IndeterminateError(PROVIDER);
+            const piece = data.mailPieces;
+            if (!isRecord(piece) || piece.mailPieceId !== number
+                || (phase === 'summary' ? !isRecord(piece.summary) : !Array.isArray(piece.events) || piece.events.length > 500)) {
+                throw new SchemaError(PROVIDER, 'Royal Mail did not return the requested parcel history');
+            }
+            // Drop proof, recipient and credential fields before merging the replies.
+            resolve(phase === 'summary' ? { mailPieceId: number, summary: piece.summary, estimatedDelivery: piece.estimatedDelivery }
+                : { mailPieceId: number, events: piece.events,
+                    ...(isRecord(piece.estimatedDelivery) ? { estimatedDelivery: { date: piece.estimatedDelivery.date } } : {}) });
+        })().catch(error => { if (active)
+            reject(carrierErrorKind(error) ? error : new TransportError(PROVIDER)); });
+    };
+    page.on('response', received);
+    page.on('requestfailed', failed);
+    deadline.addEventListener('abort', aborted, { once: true });
+    try {
+        deadline.throwIfAborted();
+        await Promise.race([trigger(), reply.then(() => { })]);
+        return await reply;
+    }
+    finally {
+        active = false;
+        page.off('response', received);
+        page.off('requestfailed', failed);
+        deadline.removeEventListener('abort', aborted);
+    }
+}
+export function fetchRoyalMailInBrowser(number, executablePath, signal, timeoutMs, fullHistory) {
+    return withLocalBrowser({ provider: PROVIDER, executablePath, signal, timeoutMs,
+        args: ['--disable-blink-features=AutomationControlled'] }, async ({ browser, signal: session, remainingMs }) => {
+        try {
+            const platform = process.platform === 'darwin' ? 'Macintosh; Intel Mac OS X 10_15_7'
+                : process.platform === 'win32' ? 'Windows NT 10.0; Win64; x64' : 'X11; Linux x86_64';
+            const major = browser.version().split('.')[0];
+            const context = await browser.newContext({ locale: 'en-GB', acceptDownloads: false, serviceWorkers: 'block',
+                userAgent: `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36` });
+            session.throwIfAborted();
+            const page = await context.newPage();
+            const timeout = () => Math.min(15_000, remainingMs());
+            const decline = async () => {
+                const button = page.getByText('Decline all', { exact: true });
+                await button.waitFor({ state: 'visible', timeout: Math.min(3_000, remainingMs()) }).catch(() => { });
+                session.throwIfAborted();
+                if (await button.isVisible()) {
+                    // Consent may reload the document and clear a number already typed.
+                    const reload = page.waitForEvent('domcontentloaded', { timeout: Math.min(4_000, remainingMs()) }).catch(() => { });
+                    await button.click({ timeout: timeout() });
+                    await reload;
+                    session.throwIfAborted();
+                }
+            };
+            // Ordinary navigation lets the public site initialize its anonymous edge
+            // session before the tracking application starts.
+            const response = await page.goto(`${ORIGIN}/`, { waitUntil: 'domcontentloaded', timeout: timeout() });
+            session.throwIfAborted();
+            if (!response)
+                throw new TransportError(PROVIDER);
+            if ([401, 403].includes(response.status()))
+                throw new ChallengeError(PROVIDER);
+            if ([404, 410].includes(response.status()))
+                throw new TransportError(PROVIDER, 'Royal Mail tracking page is unavailable');
+            if (response.status() !== 200)
+                throw new UpstreamHttpError(PROVIDER, response.status());
+            if (new URL(page.url()).origin !== ORIGIN)
+                throw new SchemaError(PROVIDER);
+            await decline();
+            const link = page.locator('a').filter({ hasText: /^\s*Track your item\s*$/i }).first();
+            await link.waitFor({ state: 'visible', timeout: timeout() });
+            const href = await link.getAttribute('href');
+            const target = new URL(href ?? '', ORIGIN);
+            if (target.origin !== ORIGIN || target.pathname !== '/track-your-item')
+                throw new SchemaError(PROVIDER);
+            // The site's fixed navigation can cover this link. Follow its validated
+            // public destination with the same browser context instead of waiting on an overlay.
+            const trackingPage = await page.goto(target.href, { waitUntil: 'domcontentloaded', timeout: timeout() });
+            session.throwIfAborted();
+            if (!trackingPage)
+                throw new TransportError(PROVIDER);
+            if ([401, 403].includes(trackingPage.status()))
+                throw new ChallengeError(PROVIDER);
+            if ([404, 410].includes(trackingPage.status()))
+                throw new TransportError(PROVIDER, 'Royal Mail tracking page is unavailable');
+            if (trackingPage.status() !== 200)
+                throw new UpstreamHttpError(PROVIDER, trackingPage.status());
+            const input = page.locator('#barcode-input');
+            await input.waitFor({ state: 'visible', timeout: timeout() });
+            await decline();
+            await input.waitFor({ state: 'visible', timeout: timeout() });
+            const landed = new URL(page.url());
+            if (landed.origin !== ORIGIN || landed.pathname !== '/track-your-item')
+                throw new SchemaError(PROVIDER);
+            await input.click({ timeout: timeout() });
+            await input.pressSequentially(number, { delay: 80, timeout: timeout() });
+            session.throwIfAborted();
+            const summary = await captureRoyalMailReply(page, royalMailSummaryApiUrl(number), number, 'summary', session, Math.min(25_000, remainingMs()), async () => {
+                if (await input.inputValue() !== number)
+                    throw new TransportError(PROVIDER, 'Royal Mail tracking form was reset');
+                await page.locator('#submit:not(:disabled)').click({ timeout: timeout() });
+            });
+            // The summary issues an API session. The application's details handler
+            // uses it, or performs its own CAPTCHA refresh when the session expires.
+            parseRoyalMailTrackingResponse({ mailPieces: summary }, number);
+            const history = fullHistory ? await captureRoyalMailReply(page, royalMailEventsApiUrl(number), number, 'events', session, Math.min(25_000, remainingMs()), () => page.locator('#btn-more-details').click({ timeout: timeout() })) : undefined;
+            session.throwIfAborted();
+            return { ...parseRoyalMailTrackingResponse({ mailPieces: { ...summary, ...(history ?? {}) } }, number),
+                tracking_url: royalMailTrackingUrl(number), tracking_source: 'structured-web-response' };
+        }
+        catch (error) {
+            session.throwIfAborted();
+            if (carrierErrorKind(error))
+                throw error;
+            // Native browser diagnostics can contain request URLs or page contents.
+            throw new TransportError(PROVIDER, 'Royal Mail browser tracking failed');
+        }
+    });
+}

package/dist/carriers/royal-mail/carrier.json

@@ -14,8 +14,10 @@
   "timezone": "UTC",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "royal-mail",
+    "steps": [
+      "browser"
+    ]
   },
   "capabilities": [
     "history",
@@ -31,7 +33,12 @@
       "eta",
       "location"
     ],
-    "scraped": [],
+    "scraped": [
+      "status",
+      "history",
+      "eta",
+      "location"
+    ],
     "discarded": [
       "signatory",
       "proof of delivery extras",

package/dist/carriers/royal-mail/parser.d.ts

@@ -0,0 +1,13 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeRoyalMailNumber(raw: string): string;
+export declare function royalMailTrackingUrl(trackingNumber: string): string;
+export declare function royalMailSummaryApiUrl(trackingNumber: string): string;
+export declare function royalMailEventsApiUrl(trackingNumber: string): string;
+/** Only the field vocabulary consumed by the public tracking application. */
+export declare function parseRoyalMailTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+/**
+ * The page the browser rendered, read only to tell a bot challenge from an
+ * inconclusive load. Rendered text never decides not-found: only the
+ * structured reply does.
+ */
+export declare function parseRoyalMailTrackingHtml(page: string): 'challenged' | 'inconclusive';

package/dist/carriers/royal-mail/parser.js

@@ -0,0 +1,140 @@
+import { DateTime } from 'luxon';
+import { load } from 'cheerio';
+import { ChallengeError, IndeterminateError, InvalidInputError, RateLimitedError, SchemaError } from '../../core/errors/index.js';
+import { clean, cleanScalar } from '../../core/transport/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { isRecord } from '../../core/types.js';
+import { royalMailEventStage, royalMailStage, royalMailSummaryStage, statusForStage } from './status.js';
+/** Read the response produced by Royal Mail's form and hCaptcha callback. */
+const TRACKING_BASE = 'https://www.royalmail.com/track-your-item';
+const SUMMARY_API_PREFIX = 'https://api-web.royalmail.com/mailpieces/microsummary/v1/summary/';
+const EVENTS_API_PREFIX = 'https://api-web.royalmail.com/mailpieces/v3/';
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+export function normalizeRoyalMailNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^[A-Z]{2}\d{9}GB$/.test(value)) {
+        throw new InvalidInputError('Royal Mail', 'Royal Mail tracking numbers must match the UPU S10 format');
+    }
+    return value;
+}
+export function royalMailTrackingUrl(trackingNumber) {
+    return `${TRACKING_BASE}#/tracking-results/${normalizeRoyalMailNumber(trackingNumber)}`;
+}
+export function royalMailSummaryApiUrl(trackingNumber) {
+    return `${SUMMARY_API_PREFIX}${normalizeRoyalMailNumber(trackingNumber)}`;
+}
+export function royalMailEventsApiUrl(trackingNumber) {
+    return `${EVENTS_API_PREFIX}${normalizeRoyalMailNumber(trackingNumber)}/events`;
+}
+/** Preserve offset-free wall time instead of assigning a zone to overseas scans. */
+function eventTime(value) {
+    const raw = cleanScalar(value, 64);
+    // A date or wall clock must never acquire the carrier's default timezone.
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-](?:(?:0\d|1[0-3]):?[0-5]\d|14:?00))$/i.test(raw))
+        return null;
+    return explicitOffsetTime(raw)?.iso ?? null;
+}
+/** A delivery estimate reduced to its calendar day. */
+function expectedDelivery(value) {
+    const raw = cleanScalar(value, 64);
+    const day = /^\d{4}-\d{2}-\d{2}/.exec(raw)?.[0];
+    return day && DateTime.fromISO(day).isValid ? day : null;
+}
+/** Only the field vocabulary consumed by the public tracking application. */
+export function parseRoyalMailTrackingResponse(payload, trackingNumber) {
+    const number = normalizeRoyalMailNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('Royal Mail', 'Royal Mail returned an invalid tracking response');
+    const errors = Array.isArray(payload.errors) ? payload.errors.filter(isRecord) : [];
+    if (errors.some(error => error.errorCode === 'E0015' || error.code === 'E0015')) {
+        throw new ChallengeError('Royal Mail', 'Royal Mail denied the tracking session');
+    }
+    if (String(payload.httpCode) === '429')
+        throw new RateLimitedError('Royal Mail');
+    if (errors.length)
+        throw new IndeterminateError('Royal Mail', 'Royal Mail could not confirm the tracking status');
+    const mailpiece = payload.mailPieces;
+    // Both summary and events endpoints return one object, not the array used by the
+    // recent-items endpoint. Never treat a gateway 404 or schema drift as not-found.
+    if (!isRecord(mailpiece) || !isRecord(mailpiece.summary)) {
+        throw new SchemaError('Royal Mail', 'Royal Mail returned an invalid tracking response');
+    }
+    if (cleanScalar(mailpiece.mailPieceId).toUpperCase() !== number) {
+        throw new SchemaError('Royal Mail', 'Royal Mail did not return the requested parcel');
+    }
+    const summary = mailpiece.summary;
+    const summaryText = cleanScalar(summary.statusDescription);
+    if (mailpiece.events !== undefined && !Array.isArray(mailpiece.events)) {
+        throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
+    }
+    const scans = Array.isArray(mailpiece.events) ? mailpiece.events : [];
+    const events = [];
+    const seen = new Set();
+    for (const raw of scans.slice(0, MAX_EVENTS_TO_INSPECT)) {
+        if (!isRecord(raw))
+            throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
+        // The website returns Markdown emphasis, including "**Delivered by**".
+        // Normalize it before classification so delivery prose is still redacted.
+        const description = cleanScalar(raw.eventName).replace(/\*\*/g, '').trim();
+        if (!description)
+            throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
+        const code = cleanScalar(raw.eventCode, 64);
+        const mapped = royalMailEventStage(code);
+        const stage = mapped ?? royalMailStage(description) ?? undefined;
+        const time = eventTime(raw.eventDateTime);
+        const timeText = cleanScalar(raw.eventDateTime, 64);
+        const location = cleanScalar(raw.locationName, 250);
+        const event = {
+            ...(time ? { time } : {}),
+            ...(!time && timeText ? { provider_time_text: timeText } : {}),
+            ...(location ? { location } : {}),
+            description: stage === 'delivered' ? 'Delivered' : description,
+            ...(stage ? { stage } : {}),
+            ...(mapped ? { stage_source: 'carrier_map' } : {}),
+            ...(/^[A-Za-z0-9_-]+$/.test(code) ? { provider_code: code } : {}),
+        };
+        const identity = JSON.stringify([time ?? timeText, location, event.description]);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        events.push(event);
+    }
+    // Royal Mail also sorts the history; upstream order is not guaranteed.
+    // A partial comparator can move resolved scans across unresolved overseas
+    // clocks. Preserve provider order unless every scan denotes an instant.
+    if (events.every(event => event.time)) {
+        events.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    }
+    const trimmed = events.slice(0, MAX_EVENTS_TO_RETURN);
+    const summaryCategory = cleanScalar(summary.statusCategory);
+    const statusText = summaryText || summaryCategory || trimmed[0]?.description;
+    if (!statusText)
+        throw new SchemaError('Royal Mail', 'Royal Mail returned no usable tracking status');
+    const stage = royalMailSummaryStage(summaryCategory, statusText) ?? undefined;
+    const delivered = stage === 'delivered';
+    return {
+        status: stage ? statusForStage(stage) : 'unknown',
+        ...(stage ? { current_stage: stage } : {}),
+        last_status_text: delivered ? 'Delivered' : statusText,
+        last_update: eventTime(summary.lastEventDateTime) || trimmed[0]?.time || null,
+        expected_delivery: delivered || !isRecord(mailpiece.estimatedDelivery)
+            ? null : expectedDelivery(mailpiece.estimatedDelivery.date),
+        events: trimmed,
+        ...(trimmed.length ? {} : { summary_only: true }),
+    };
+}
+/**
+ * The page the browser rendered, read only to tell a bot challenge from an
+ * inconclusive load. Rendered text never decides not-found: only the
+ * structured reply does.
+ */
+export function parseRoyalMailTrackingHtml(page) {
+    const $ = load(page);
+    $('script, style, noscript').remove();
+    const visible = clean($('body').text(), 20_000);
+    if (/access denied|just a moment|attention required|are you a robot|verify you are human|before you proceed|unusual traffic/i.test(visible)) {
+        return 'challenged';
+    }
+    return 'inconclusive';
+}

package/dist/data/catalog.json

@@ -1741,7 +1741,7 @@
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "royal-mail"
         },
         "canaryUrl": "https://www.royalmail.com/track-your-item",
         "trackingUrlTemplate": "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",

package/dist/generated/catalog.d.ts

@@ -1121,7 +1121,7 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "UTC";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "royal-mail";
         };
         readonly canaryUrl: "https://www.royalmail.com/track-your-item";
         readonly trackingUrlTemplate: "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}";

package/dist/generated/catalog.js

@@ -1742,7 +1742,7 @@ export const CARRIER_CATALOG = {
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "royal-mail"
         },
         "canaryUrl": "https://www.royalmail.com/track-your-item",
         "trackingUrlTemplate": "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",

package/dist/generated/registry.js

@@ -289,7 +289,7 @@ export const REGISTRY = {
         "purolator": "purolator",
         "quickpac": "planzer",
         "relais-colis": "relais-colis",
-        "royal-mail": "universal",
+        "royal-mail": "royal-mail",
         "sagawa": "universal",
         "seur": "seur",
         "sf-express": "sf-express",

package/dist/providers/coverage.json

@@ -139,8 +139,8 @@
     },
     {
       "carrier": "royal-mail",
-      "direct": "Disabled",
-      "sample": "Error",
+      "direct": "Yes (local Chromium)",
+      "sample": "\u2713 8",
       "references": [
         {
           "results": {
@@ -152,7 +152,7 @@
           }
         },
         {
-          "note": "Alternate public reference returned eight identity-bound full-history scans in an interactive official session. Fresh automated Chromium obtained the matching microsummary, but its separate events request failed; automated full history remains unverified: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/",
+          "note": "Public references returned eight and six identity-bound history scans in fresh automated Chromium on both local and Linux server hosts: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/ and https://www.reddit.com/r/Sugargoo/comments/1we8q17/where_is_my_parcel/. The official documentation example returned E1142, which remains inconclusive. Anonymous requests can still stall before the API request or be reset; browser and runtime compatibility matter. TRAWL deployment compatibility is unverified.",
           "results": {}
         }
       ]

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.13.1"
+    "version": "0.14.0"
   },
   "paths": {
     "/health": {

package/package.json

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