universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/relais-colis/statuses.json

@@ -0,0 +1,341 @@
+{
+  "carrier": "relais-colis",
+  "entries": [
+    {
+      "wording": "retour a l expediteur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Return fragments apply only after excluding planned or ongoing return wording."
+    },
+    {
+      "wording": "retourne a l expediteur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Return fragments apply only after excluding planned or ongoing return wording."
+    },
+    {
+      "wording": "retourne a votre vendeur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Return fragments apply only after excluding planned or ongoing return wording."
+    },
+    {
+      "wording": "retour a votre vendeur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Return fragments apply only after excluding planned or ongoing return wording."
+    },
+    {
+      "wording": "retour vendeur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Return fragments apply only after excluding planned or ongoing return wording."
+    },
+    {
+      "wording": "livraison impossible",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "echec de livraison",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "incident de livraison",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "adresse incorrecte",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "colis endommage",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "colis refuse",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "colis perdu",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "destinataire absent",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "n a pas pu etre livre",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "disponible dans votre relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Matched on the fixture step \"Votre colis est disponible dans votre Relais Colis\"."
+    },
+    {
+      "wording": "disponible au relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "disponible en relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "mis a disposition dans votre relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "vous attend dans votre relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "a retirer dans votre relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "en cours de livraison",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Exercised by the offline out-for-delivery scenario; tested before the delivery rules so \"livraison dans votre relais\" cannot read as delivered."
+    },
+    {
+      "wording": "en cours de distribution",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "livraison dans votre relais",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "retire par le destinataire",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "remis au destinataire",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "remis a son destinataire",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "livraison effectuee",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "colis|commande a ete|est livre",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Regular expression rather than a fragment; exercised by the offline \"Votre colis a été livré au destinataire\" scenario."
+    },
+    {
+      "wording": "commande enregistree",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "colis annonce",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "colis a ete annonce",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Matched on the fixture step \"Votre colis a été annoncé\"."
+    },
+    {
+      "wording": "information transmise",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "en attente de prise en charge",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "sera prochainement confie",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "pris en charge",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Matched on the fixture step \"Votre colis a été pris en charge\"."
+    },
+    {
+      "wording": "en cours d acheminement",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Matched on the fixture step \"Votre colis est en cours d'acheminement dans notre réseau\"."
+    },
+    {
+      "wording": "en transit",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "arrive dans notre agence",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "arrive sur notre agence",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "a quitte notre agence",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "achemine vers",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    },
+    {
+      "wording": "expedie vers",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "prior-art",
+      "firstSeen": "2026-09-12",
+      "note": "Sentence fragment inherited from the pre-package adapter; source not recorded."
+    }
+  ]
+}

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

@@ -0,0 +1,32 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+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;
+/** 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 interface RoyalMailTrackerOptions {
+    timeoutMs?: number;
+    /** Legacy configuration seam; `trawl` is preferred. */
+    trawlUrl?: string;
+    /** The browser service, or null when none is configured. */
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class RoyalMailTracker {
+    #private;
+    readonly timeoutMs: number;
+    readonly trawlUrl: string;
+    constructor(options?: RoyalMailTrackerOptions);
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

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

@@ -0,0 +1,260 @@
+import { DateTime } from 'luxon';
+import { load } from 'cheerio';
+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, TrawlClient } from '../../core/transport/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { isRecord } from '../../core/types.js';
+import { 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 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 SchemaError('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)}`;
+}
+/** Preserve offset-free wall time instead of assigning a zone to overseas scans. */
+function eventTime(value) {
+    const raw = cleanScalar(value, 64);
+    return explicitOffsetTime(raw)?.iso ?? raw;
+}
+/** 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;
+    // The microsummary endpoint returns 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))
+            continue;
+        const description = cleanScalar(raw.eventName);
+        if (!description)
+            continue;
+        const stage = royalMailStage(description) ?? undefined;
+        const time = eventTime(raw.eventDateTime);
+        const location = cleanScalar(raw.locationName, 250);
+        const code = cleanScalar(raw.eventCode, 64);
+        const event = {
+            ...(time ? { time } : {}),
+            ...(location ? { location } : {}),
+            description: stage === 'delivered' ? 'Delivered' : description,
+            ...(stage ? { stage } : {}),
+            ...(/^[A-Za-z0-9_-]+$/.test(code) ? { provider_code: code } : {}),
+        };
+        const identity = JSON.stringify([time, 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.
+    events.sort((a, b) => {
+        const left = Date.parse(a.time ?? '');
+        const right = Date.parse(b.time ?? '');
+        return Number.isFinite(left) && Number.isFinite(right) ? right - left : 0;
+    });
+    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,
+    };
+}
+/**
+ * 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;
+    #trawl;
+    #fetcher;
+    #recorder;
+    constructor(options = {}) {
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+            throw new TypeError('Royal Mail timeout must be positive');
+        }
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.trawlUrl = (options.trawlUrl ?? '').trim();
+        this.#trawl = options.trawl;
+        this.#fetcher = options.fetcher;
+        this.#recorder = options.recorder ?? NOOP_RECORDER;
+    }
+    /** The injected browser service, or one built from the configured URL. */
+    #browserService() {
+        if (this.#trawl !== undefined)
+            return this.#trawl;
+        return this.trawlUrl ? new TrawlClient(this.trawlUrl, this.#fetcher) : null;
+    }
+    async fetch(trackingNumber) {
+        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.
+        const trawl = this.#browserService();
+        if (!trawl) {
+            throw new ChallengeError('Royal Mail', 'Royal Mail challenged direct tracking; configure FLARESOLVERR_URL for browser fallback');
+        }
+        return runSteps({
+            carrier: 'royal-mail', budgetMs: this.timeoutMs, recorder: this.#recorder,
+        }, [
+            { id: 'trawl', run: () => this.#trawlResult(trawl, number) },
+        ]);
+    }
+    /**
+     * A real browser loads the page and makes the summary call itself; the
+     * service hands that reply back. The browser's session is never replayed
+     * over plain HTTP: the edge accepts the call only from the session it
+     * validated. The page the browser rendered only tells a challenge apart.
+     */
+    async #trawlResult(trawl, number) {
+        const summaryUrl = royalMailSummaryApiUrl(number);
+        const page = await trawl.scrape({
+            url: royalMailTrackingUrl(number),
+            skipHttp: true,
+            maxTier: 3,
+            maxTimeout: this.timeoutMs,
+            captureResponses: [summaryUrl],
+            settleTimeout: SETTLE_TIMEOUT_MS,
+        }, {
+            provider: 'TRAWL while fetching Royal Mail',
+            // A browser may validate its cached main document with 304 while the
+            // freshly submitted tracking request still returns a normal JSON reply.
+            requireSolved: false,
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_BYTES,
+            fetcher: this.#fetcher,
+        });
+        if (![2, 3].includes(page.tier) || ![200, 304].includes(page.statusCode)) {
+            throw new TransportError('Royal Mail', 'The browser service did not load the Royal Mail tracking page');
+        }
+        let captureError;
+        // Newest first: a later reply is the page's final answer. The entry URL
+        // itself carries the number, so only the exact requested call is read.
+        for (const entry of page.capturedResponses.slice(0, MAX_CAPTURED).reverse()) {
+            if (entry.url !== summaryUrl)
+                continue;
+            if (entry.status === 429) {
+                const retry = entry.headers['retry-after'];
+                const retryMs = retry && /^\d+$/.test(retry) ? Number(retry) * 1_000 : undefined;
+                throw new RateLimitedError('Royal Mail', retryMs);
+            }
+            if ([401, 403].includes(entry.status))
+                throw new ChallengeError('Royal Mail');
+            if (entry.status === 404 && entry.body && !entry.truncated && !entry.base64Encoded && !entry.error) {
+                let payload;
+                try {
+                    payload = JSON.parse(entry.body);
+                }
+                catch { /* Keep the HTTP failure below. */ }
+                if (isRecord(payload) && Array.isArray(payload.errors)
+                    && payload.errors.some(error => isRecord(error) && error.errorCode === 'E1142')) {
+                    throw new IndeterminateError('Royal Mail', 'Royal Mail could not confirm the tracking status');
+                }
+            }
+            if (entry.status >= 400)
+                throw new UpstreamHttpError('Royal Mail', entry.status);
+            if (entry.status !== 200 || entry.truncated || entry.base64Encoded || entry.error || entry.body === null)
+                continue;
+            try {
+                return this.#structuredResult(number, JSON.parse(entry.body));
+            }
+            catch (error) {
+                // An unreadable or unrelated reply; the rendered page may still name a challenge.
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                captureError = error;
+            }
+        }
+        if (parseRoyalMailTrackingHtml(page.html) === 'challenged') {
+            throw new ChallengeError('Royal Mail', 'Royal Mail challenged the browser tracking session', { cause: captureError });
+        }
+        throw new TransportError('Royal Mail', 'TRAWL did not capture the Royal Mail tracking response', { cause: captureError });
+    }
+    #structuredResult(number, payload) {
+        const result = parseRoyalMailTrackingResponse(payload, number);
+        result.tracking_url = royalMailTrackingUrl(number);
+        result.tracking_source = 'structured-web-response';
+        return result;
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new RoyalMailTracker({
+        fetcher: environment.fetcher,
+        trawl: environment.trawl,
+        recorder: environment.recorder,
+    });
+    return {
+        id: 'royal-mail',
+        // Akamai refuses every non-browser client, so there is no direct tier.
+        steps: ['trawl'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};