universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,101 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { IndeterminateError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
+import { koreaPostStatus } from './status.js';
+const ENDPOINT = 'https://trace.epost.go.kr/xtts/servlet/kpl.tts.common.svl.SttSVL';
+export function normalizeKoreaPostNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^[A-Z]{2}\d{9}[A-Z]{2}$/.test(number))
+        throw new InputRequiredError('Korea Post', 'number', 'Korea Post direct tracking supports international postal identifiers');
+    return number;
+}
+function eventTime(raw) {
+    const parsed = DateTime.fromFormat(raw, 'HH:mm dd-LLL-yyyy', { zone: 'UTC', locale: 'en-US' });
+    if (!parsed.isValid)
+        throw new SchemaError('Korea Post', 'Korea Post returned an invalid scan time');
+    // The portal explicitly uses destination-local time after handover. Preserve
+    // its sequence and wall clocks; a Korea-wide timezone would corrupt these.
+    return parsed.toISO({ suppressMilliseconds: true, includeOffset: false });
+}
+export function parse(html, trackingNumber) {
+    const number = normalizeKoreaPostNumber(trackingNumber);
+    const $ = load(html);
+    $('script, style, noscript').remove();
+    $('br').replaceWith(' ');
+    const basic = $('table').filter((_, element) => $(element).attr('summary') === 'Basic Information');
+    const basicRows = basic.find('tbody > tr');
+    if (basic.length !== 1 || basicRows.length !== 1 || clean(basicRows.children('td').first().text()) !== number)
+        throw new SchemaError('Korea Post', 'Korea Post returned a different or ambiguous shipment');
+    const history = $('table').filter((_, element) => clean($(element).find('thead th').map((__, cell) => clean($(cell).text())).get().join('|')) === 'Date|Status|Post office/Airport|Details');
+    if (history.length !== 1)
+        throw new SchemaError('Korea Post', 'Korea Post returned an invalid tracking table');
+    const rows = history.find('tbody > tr');
+    if (rows.length === 1 && rows.children('td').length === 1 && rows.children('td').attr('colspan') === '4'
+        && clean(rows.text()) === `Your item number ${number} is not found. Confirm your item number.`)
+        throw new NotFoundError('Korea Post');
+    if (!rows.length)
+        throw new IndeterminateError('Korea Post', 'Korea Post returned no parcel scans');
+    if (rows.length > 500)
+        throw new SchemaError('Korea Post');
+    const events = [];
+    const seen = new Set();
+    for (const row of rows.toArray().reverse()) {
+        const cells = $(row).children('td');
+        if (cells.length !== 4 || cells.filter('[colspan]').length)
+            throw new SchemaError('Korea Post');
+        const time = eventTime(clean(cells.eq(0).text(), 64));
+        const description = clean(cells.eq(1).text(), 500);
+        if (!description)
+            throw new SchemaError('Korea Post', 'Korea Post returned an empty scan');
+        const location = clean(cells.eq(2).text(), 200);
+        const key = JSON.stringify([time, description, location]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const classified = koreaPostStatus(description);
+        // The fourth cell mixes routing notes with recipient names and results;
+        // project only the dedicated timestamp, status and facility columns.
+        events.push({ local_time: time, description, location, ...(classified ? { stage: classified.stage } : {}) });
+    }
+    const latest = events[0];
+    const classified = koreaPostStatus(latest.description);
+    return { status: classified?.status ?? 'unknown', ...(classified ? { current_stage: classified.stage } : {}),
+        last_status_text: latest.description, last_update: null, events: events.slice(0, 100) };
+}
+export class KoreaPostTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeKoreaPostNumber(raw);
+        const budgetMs = context.budgetMs ?? 15_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('Korea Post timeout must be positive');
+        context.signal?.throwIfAborted();
+        try {
+            const { bytes } = await fetchBounded(ENDPOINT, { method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'text/html,*/*;q=0.8' },
+                body: new URLSearchParams({ target_command: 'kpl.tts.tt.epost.cmd.RetrieveEmsTraceEngCmd',
+                    JspURI: '/xtts/tt/epost/ems/EmsSearchResultEng.jsp', POST_CODE: number }).toString(),
+            }, { provider: 'Korea Post', timeoutMs: Math.max(1, Math.floor(budgetMs)), maxBytes: 1_000_000,
+                fetcher: (input, init) => (this.options.fetcher ?? fetch)(input, { ...init,
+                    signal: AbortSignal.any([...(context.signal ? [context.signal] : []), ...(init?.signal ? [init.signal] : [])]) }),
+            });
+            context.signal?.throwIfAborted();
+            return parse(decodeText(bytes), number);
+        }
+        catch (error) {
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                throw new TransportError('Korea Post', 'Korea Post tracking endpoint is unavailable', { cause: error });
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new KoreaPostTracker({ fetcher: environment.fetcher });
+    return { id: 'korea-post', recordsSteps: true, steps: ['direct'], track: (input, context = {}) => runSteps({ carrier: 'korea-post', budgetMs: context.budgetMs ?? 15_000,
+            signal: context.signal, recorder: environment.recorder }, [{ id: 'direct', run: ({ signal, remainingMs }) => tracker.fetch(input.number, { signal, budgetMs: remainingMs }) }]) };
+};

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

@@ -0,0 +1,74 @@
+{
+  "id": "korea-post",
+  "displayName": "Korea Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "KR"
+    ]
+  },
+  "brand": {
+    "color": "#da291c"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "korea-post",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://trace.epost.go.kr/xtts/servlet/kpl.tts.common.svl.SttSVL?target_command=kpl.tts.tt.epost.cmd.RetrieveEmsTraceEngCmd&JspURI=%2Fxtts%2Ftt%2Fepost%2Fems%2FEmsSearchResultEng.jsp&POST_CODE={trackingNumber}",
+    "canaryUrl": "https://trace.epost.go.kr/xtts/tt/epost/ems/ems_eng.jsp",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "trace.epost.go.kr"
+      ],
+      "params": [
+        "POST_CODE"
+      ]
+    },
+    {
+      "domains": [
+        "service.epost.go.kr"
+      ],
+      "params": [
+        "sid1"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "korea-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}KR$",
+      "confidence": "high",
+      "checksum": "s10"
+    },
+    {
+      "id": "korea-post-2",
+      "pattern": "^6\\d{12}$",
+      "confidence": "low"
+    }
+  ]
+}

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

@@ -0,0 +1,54 @@
+{
+  "carrier": "korea-post",
+  "records": [
+    {
+      "number": "6097542557191",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://kin.naver.com/qna/detail.naver?dirId=81302&docId=495290455",
+        "date": "2026-09-24"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda",
+          "korea-post"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Korea Post, which stays one candidate among several. Domestic parcel."
+    },
+    {
+      "number": "EM385783825KR",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "korea-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "ES401809342KR",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://kin.naver.com/qna/detail.naver?dirId=81302&docId=495261561",
+        "date": "2026-09-22"
+      },
+      "expect": {
+        "carrier": "korea-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. EMS item to Japan."
+    }
+  ]
+}

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

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function koreaPostStatus(description: string): ClassifiedStatus | undefined;

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

@@ -0,0 +1,19 @@
+const WORDING = new Map([
+    ['Posting/Collection', { status: 'in_transit', stage: 'accepted' }],
+    ['Departure from inward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at Office of Exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at outward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Ready for dispatch', { status: 'in_transit', stage: 'in_transit' }],
+    ['Handed over to a transport company', { status: 'in_transit', stage: 'in_transit' }],
+    ['Received by Air carriers', { status: 'in_transit', stage: 'in_transit' }],
+    ['Departure from the Airport', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at Destination Airport', { status: 'in_transit', stage: 'in_transit' }],
+    ['Delivered to Destination Post', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at inward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Ready for customs clearance', { status: 'in_transit', stage: 'customs' }],
+    ['Unsuccessful delivery', { status: 'exception', stage: 'failed_attempt' }],
+    ['Delivery complete', { status: 'delivered', stage: 'delivered' }],
+]);
+export function koreaPostStatus(description) {
+    return WORDING.get(description);
+}

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

@@ -0,0 +1,103 @@
+{
+  "carrier": "korea-post",
+  "entries": [
+    {
+      "wording": "Posting/Collection",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Departure from inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrival at Office of Exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrival at outward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Ready for dispatch",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Handed over to a transport company",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Received by Air carriers",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Departure from the Airport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrival at Destination Airport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Delivered to Destination Post",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrival at inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Ready for customs clearance",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Unsuccessful delivery",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Delivery complete",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    }
+  ]
+}

package/dist/carriers/la-poste/adapter.d.ts

@@ -0,0 +1,29 @@
+import { type AdapterFactory } from '../../core/adapter/index.js';
+import { CarrierError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import type { StepRecorder } from '../../core/telemetry/index.js';
+/**
+ * A provider `returnCode` that is not a success. Code 104 is a positive
+ * not-found; anything else only proves the feed could not answer.
+ */
+export declare class LaPosteTrackingError extends CarrierError {
+    readonly code: number | null;
+    constructor(code: number | null);
+}
+export declare function normalizeLaPosteTrackingNumber(raw: string): string;
+export declare function laPosteTrackingUrl(trackingNumber: string): string;
+export declare function laPosteTrackingApiUrl(trackingNumber: string): string;
+export declare function parseLaPosteTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export interface LaPosteTrackerOptions {
+    timeoutMs?: number;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class LaPosteTracker {
+    readonly timeoutMs: number;
+    private readonly fetcher?;
+    private readonly recorder?;
+    constructor(options?: LaPosteTrackerOptions);
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/la-poste/adapter.js

@@ -0,0 +1,241 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { carrierIdFromPartner } from '../../core/catalog/hints.js';
+import { CarrierError, SchemaError, UpstreamHttpError, } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { isoTime } from '../../core/time/index.js';
+import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { eventStage, eventStatus } from './status.js';
+// Protocol provenance:
+// - `suivi-unifie` is the keyless feed the public tracking page calls: one
+//   array entry per requested number, each with a `returnCode`, a `shipment`
+//   and its `event` list. It covers Colissimo, tracked mail, Chronopost and
+//   Delivengo, which is why those carriers share this adapter.
+// - The response is matched on `shipment.idShip`: a feed entry for another
+//   number is refused rather than projected.
+// - `returnCode` 104 is the positive "unknown shipment"; any other non-zero
+//   code is an inconclusive provider failure.
+// - Production HTTP 403s carried La Poste's "Site indisponible - Incident en
+//   cours" page and immediately following checks succeeded, so a 403 is
+//   retried up to three times inside the original deadline (see README.md).
+const TRACKING_API = 'https://www.laposte.fr/ssu/sun/back/suivi-unifie';
+const TRACKING_PAGE = 'https://www.laposte.fr/outils/suivre-vos-envois';
+const TIMEZONE = 'Europe/Paris';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+const MAX_EVENTS_TO_RETURN = 100;
+/** The provider's "unknown shipment" return code. */
+const UNKNOWN_SHIPMENT_CODE = 104;
+function number(value) {
+    if (typeof value !== 'number' && (typeof value !== 'string' || !value.trim()))
+        return null;
+    const parsed = typeof value === 'number' ? value : Number(value.trim());
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function eventOrder(event) {
+    return number(event.order) ?? -1;
+}
+/**
+ * Event timestamps already carry their Paris offset, so the provider's own
+ * string is retained verbatim; only calendar-impossible values are dropped.
+ */
+function safeDate(value) {
+    const raw = clean(value, 64);
+    if (!/^\d{4}-\d{2}-\d{2}(?:[T ][0-9:+.Z-]+)?$/i.test(raw))
+        return '';
+    return isoTime(raw, TIMEZONE) ? raw : '';
+}
+function expectedDate(value) {
+    const text = safeDate(value);
+    return /^\d{4}-\d{2}-\d{2}/.exec(text)?.[0] ?? null;
+}
+/**
+ * A provider `returnCode` that is not a success. Code 104 is a positive
+ * not-found; anything else only proves the feed could not answer.
+ */
+export class LaPosteTrackingError extends CarrierError {
+    code;
+    constructor(code) {
+        super(code === UNKNOWN_SHIPMENT_CODE ? 'not_found' : 'indeterminate', 'La Poste', code === UNKNOWN_SHIPMENT_CODE
+            ? 'La Poste could not locate the shipment'
+            : 'La Poste tracking is unavailable');
+        this.name = 'LaPosteTrackingError';
+        this.code = code;
+    }
+}
+export function normalizeLaPosteTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    const domestic = /^[A-Z0-9]{2}\d{11}$/.test(value);
+    const international = /^[A-Z]{2}\d{9}[A-Z]{2}$/.test(value);
+    const foreignExpress = /^\d{14}[A-Z]$/.test(value);
+    if (!domestic && !international && !foreignExpress) {
+        throw new TypeError('La Poste tracking numbers must use a supported 13- or 15-character format');
+    }
+    return value;
+}
+export function laPosteTrackingUrl(trackingNumber) {
+    const url = new URL(TRACKING_PAGE);
+    url.searchParams.set('code', normalizeLaPosteTrackingNumber(trackingNumber));
+    return url.toString();
+}
+export function laPosteTrackingApiUrl(trackingNumber) {
+    const normalized = normalizeLaPosteTrackingNumber(trackingNumber);
+    const url = new URL(`${TRACKING_API}/${encodeURIComponent(normalized)}`);
+    url.searchParams.set('lang', 'fr');
+    return url.toString();
+}
+export function parseLaPosteTrackingResponse(payload, trackingNumber) {
+    const requested = normalizeLaPosteTrackingNumber(trackingNumber);
+    if (!Array.isArray(payload) || payload.length === 0) {
+        throw new SchemaError('La Poste', 'La Poste returned an invalid tracking response');
+    }
+    const responses = payload.filter(isRecord);
+    if (responses.length === 0) {
+        throw new SchemaError('La Poste', 'La Poste returned an invalid tracking response');
+    }
+    const response = responses.find((candidate) => {
+        const shipment = isRecord(candidate.shipment) ? candidate.shipment : {};
+        return clean(shipment.idShip, 64).toLocaleUpperCase('en-US') === requested;
+    });
+    if (!response) {
+        const providerError = responses.find((candidate) => ![0, 200].includes(number(candidate.returnCode) ?? -1));
+        if (providerError) {
+            throw new LaPosteTrackingError(number(providerError.returnCode));
+        }
+        throw new SchemaError('La Poste', 'La Poste returned a different shipment');
+    }
+    const returnCode = number(response.returnCode);
+    if (returnCode === null || ![0, 200].includes(returnCode)) {
+        throw new LaPosteTrackingError(returnCode);
+    }
+    const shipment = isRecord(response.shipment) ? response.shipment : {};
+    const rawEvents = records(shipment.event).sort((left, right) => {
+        const orderDifference = eventOrder(right) - eventOrder(left);
+        if (orderDifference !== 0)
+            return orderDifference;
+        return safeDate(right.date).localeCompare(safeDate(left.date));
+    });
+    // Projection allowlist: nothing but status wording, time, coarse location and
+    // the provider's own codes leaves this function. Recipient blocks, addresses
+    // and proof-of-delivery fields in the payload are never read.
+    const events = rawEvents.slice(0, MAX_EVENTS_TO_RETURN).flatMap((event) => {
+        const description = clean(event.label);
+        const time = safeDate(event.date);
+        if (!description && !time)
+            return [];
+        const group = clean(event.group, 40).toLocaleUpperCase('en-US');
+        const code = clean(event.code, 40).toLocaleUpperCase('en-US');
+        return [{
+                time,
+                location: clean(event.country, 80),
+                description: description || 'Tracking update',
+                stage: eventStage(group, code, description),
+                ...(group || code ? { provider_code: [group, code].filter(Boolean).join('/') } : {}),
+            }];
+    });
+    const latestRaw = rawEvents[0] ?? {};
+    const latest = events[0];
+    const timeline = records(shipment.timeline)
+        .filter((step) => step.status === true)
+        .sort((left, right) => (number(right.id) ?? -1) - (number(left.id) ?? -1));
+    const currentState = isRecord(shipment.currentState) ? shipment.currentState : {};
+    const fallbackLabel = clean(currentState.shortLabel) || clean(timeline[0]?.shortLabel);
+    const latestLabel = latest?.description || fallbackLabel || clean(response.returnMessage);
+    const latestGroup = clean(latestRaw.group, 40);
+    const latestCode = clean(latestRaw.code, 40);
+    const context = isRecord(shipment.contextData) ? shipment.contextData : {};
+    const destination = clean(context.arrivalCountry, 80).toUpperCase();
+    const partner = isRecord(context.partner) ? context.partner : {};
+    const deliveryCarrier = carrierIdFromPartner(clean(partner.name, 80), clean(partner.url, 2048));
+    const deliveryNumber = clean(partner.reference, 64).toUpperCase();
+    return {
+        status: eventStatus(latestGroup, latestCode, latestLabel, events.length > 0),
+        // The status vocabulary has no pickup or customs value; without the stage
+        // the sync would re-read the sentence and fall back to "out for delivery".
+        ...(latest?.stage ? { current_stage: latest.stage } : {}),
+        last_status_text: latestLabel || 'Tracking information received',
+        last_update: latest?.time || safeDate(timeline[0]?.date) || null,
+        expected_delivery: shipment.isFinal === true ? null : expectedDate(shipment.estimDate),
+        timezone: TIMEZONE,
+        ...(/^[A-Z]{2}$/.test(destination) ? { destination_country: destination } : {}),
+        ...(deliveryCarrier ? {
+            delivery_carrier: deliveryCarrier,
+            ...(/^[A-Z0-9]{4,40}$/.test(deliveryNumber) ? { delivery_tracking_number: deliveryNumber } : {}),
+        } : {}),
+        events,
+    };
+}
+export class LaPosteTracker {
+    timeoutMs;
+    fetcher;
+    recorder;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('La Poste timeout must be positive');
+        }
+        this.fetcher = options.fetcher;
+        this.recorder = options.recorder;
+    }
+    async fetch(trackingNumber) {
+        const normalized = normalizeLaPosteTrackingNumber(trackingNumber);
+        const deadline = performance.now() + this.timeoutMs;
+        const request = async (remainingMs) => {
+            const { bytes } = await fetchBounded(laPosteTrackingApiUrl(normalized), {
+                headers: {
+                    Accept: 'application/json, text/plain, */*',
+                    'Accept-Language': 'fr-FR,fr;q=0.9',
+                    Referer: laPosteTrackingUrl(normalized),
+                    'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+                },
+            }, {
+                provider: 'La Poste tracking',
+                timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                maxBytes: MAX_RESPONSE_BYTES,
+                fetcher: this.fetcher,
+            });
+            return parseLaPosteTrackingResponse(parseJsonBytes(bytes, 'La Poste'), normalized);
+        };
+        // La Poste's edge answers single lookups with an HTTP 403 "Site indisponible
+        // - Incident en cours" page while another parcel, or the same one a moment
+        // later, is answered normally. It is a hiccup of that one request, not
+        // maintenance, so the page is retried like any other 403: three immediate
+        // retries sharing the original deadline. A real incident still fails every
+        // attempt within seconds and reaches the router. Do not retry other HTTP or
+        // parsing failures. Once the deadline is spent the retry is refused, so the
+        // caller still sees the provider's own rejection rather than a budget error.
+        const retriable = (error) => error instanceof UpstreamHttpError
+            && error.status === 403
+            && deadline - performance.now() >= 1;
+        const retry = {
+            id: 'retry',
+            recovers: retriable,
+            run: ({ remainingMs }) => request(remainingMs),
+        };
+        return await runSteps({
+            carrier: 'la-poste', budgetMs: this.timeoutMs, recorder: this.recorder,
+        }, [
+            { id: 'direct', run: ({ remainingMs }) => request(remainingMs) },
+            retry,
+            { ...retry },
+            { ...retry },
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new LaPosteTracker({
+        fetcher: environment.fetcher,
+        recorder: environment.recorder,
+    });
+    return {
+        id: 'la-poste',
+        // One keyless request, then up to three immediate retries of the same
+        // request after a transient HTTP 403, inside the original deadline.
+        steps: ['direct', 'retry'],
+        track: (input) => tracker.fetch(input.number),
+        recognize: (number) => recognizeFromLookup(() => tracker.fetch(number), () => accepted(() => normalizeLaPosteTrackingNumber(number))),
+    };
+};