universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/yunda/carrier.json

@@ -0,0 +1,69 @@
+{
+  "id": "yunda",
+  "displayName": "Yunda Express",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#ffce00"
+  },
+  "selectable": true,
+  "timezone": "Asia/Shanghai",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "yunda",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://web.yundaex.com/infoInquiry?nav_id=262&cid=0&homeWaybill={trackingNumber}",
+    "canaryUrl": "https://web.yundaex.com/infoInquiry",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "contact_details",
+      "recipient_details",
+      "collection_addresses",
+      "signature_images",
+      "unlabelled_weight"
+    ],
+    "unavailable": [
+      "eta",
+      "pickup_point"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "web.yundaex.com"
+      ],
+      "params": [
+        "homeWaybill"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "yunda-1",
+      "pattern": "^\\d{13}(?:\\d{2})?$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/yunda/challenge.d.ts

@@ -0,0 +1,5 @@
+/** The current client's native PNG geometry, not rendered browser coordinates. */
+export declare function solveYundaSlider(value: unknown, signal?: AbortSignal): Promise<{
+    x: number;
+    y: number;
+}>;

package/dist/carriers/yunda/challenge.js

@@ -0,0 +1,68 @@
+import { loadSharp } from '../../core/transport/optional.js';
+import { ChallengeError, SchemaError } from '../../core/errors/index.js';
+import { isRecord } from '../../core/types.js';
+const PROVIDER = 'Yunda Express';
+const PNG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+async function pixels(raw, width, height) {
+    if (typeof raw !== 'string' || raw.length > 700_000 || !/^[A-Za-z\d+/]+={0,2}$/.test(raw))
+        throw new SchemaError(PROVIDER, 'Yunda returned an invalid challenge image');
+    const bytes = Buffer.from(raw, 'base64');
+    if (!bytes.subarray(0, 8).equals(PNG))
+        throw new SchemaError(PROVIDER, 'Yunda returned an unsupported challenge image');
+    try {
+        const sharp = await loadSharp('Yunda');
+        const decoder = sharp(bytes, { limitInputPixels: 60_000, failOn: 'warning' });
+        const metadata = await decoder.metadata();
+        if (metadata.format !== 'png' || metadata.width !== width || metadata.height !== height || (width === 40 && !metadata.hasAlpha)) {
+            throw new ChallengeError(PROVIDER, 'Yunda changed its slider image layout');
+        }
+        return await decoder.toColourspace('srgb').ensureAlpha().raw().toBuffer();
+    }
+    catch (error) {
+        if (error instanceof ChallengeError)
+            throw error;
+        throw new SchemaError(PROVIDER, 'Yunda returned an undecodable challenge image', { cause: error });
+    }
+}
+/** The current client's native PNG geometry, not rendered browser coordinates. */
+export async function solveYundaSlider(value, signal) {
+    signal?.throwIfAborted();
+    if (!isRecord(value) || !Number.isInteger(value.y) || Number(value.y) < 0 || Number(value.y) > 112)
+        throw new SchemaError(PROVIDER, 'Yunda returned an invalid slider row');
+    const [big, small] = await Promise.all([pixels(value.big, 344, 152), pixels(value.small, 40, 40)]);
+    signal?.throwIfAborted();
+    let maskSize = 0;
+    for (let i = 3; i < small.length; i += 4)
+        if (small[i] > 127)
+            maskSize++;
+    if (maskSize < 200 || maskSize > 1400)
+        throw new ChallengeError(PROVIDER, 'Yunda returned an unsupported slider outline');
+    const y = Number(value.y);
+    const scores = [];
+    // The deployed challenge removes the piece with white fill. Texture cannot
+    // match missing pixels; compare the transparent piece outline to that gap.
+    // The official moveX/sliderUp handler rejects coordinates above 300 even
+    // though the image has four additional pixels at the right edge.
+    for (let x = 0; x <= 300; x++) {
+        let overlap = 0;
+        let white = 0;
+        for (let row = 0; row < 40; row++)
+            for (let col = 0; col < 40; col++) {
+                const source = ((row + y) * 344 + x + col) * 4;
+                const hole = big[source] >= 250 && big[source + 1] >= 250 && big[source + 2] >= 250;
+                if (hole) {
+                    white++;
+                    if (small[(row * 40 + col) * 4 + 3] > 127)
+                        overlap++;
+                }
+            }
+        scores.push({ x, score: 2 * overlap / (maskSize + white) });
+    }
+    scores.sort((a, b) => b.score - a.score);
+    const best = scores[0];
+    const other = scores.find(candidate => Math.abs(candidate.x - best.x) > 3);
+    if (best.score < 0.98 || best.score - other.score < 0.1)
+        throw new ChallengeError(PROVIDER, 'Yunda slider match is uncertain');
+    signal?.throwIfAborted();
+    return { x: best.x, y };
+}

package/dist/carriers/yunda/numbers.json

@@ -0,0 +1,43 @@
+{
+  "carrier": "yunda",
+  "records": [
+    {
+      "number": "1000478495775",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Yunda Express, which stays one candidate among several."
+    },
+    {
+      "number": "000000000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-28",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "dpd-fr",
+          "yunda"
+        ]
+      },
+      "note": "Synthetic domestic waybill shape; its length is shared with FedEx and DPD France, so it stays ambiguous."
+    }
+  ]
+}

package/dist/carriers/yunda/parser.d.ts

@@ -0,0 +1,4 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeYundaNumber(raw: string): string;
+export declare function yundaEnvelope(payload: unknown): Record<string, unknown>;
+export declare function parseYunda(payload: unknown, trackingNumber: string): CarrierResult;

package/dist/carriers/yunda/parser.js

@@ -0,0 +1,105 @@
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { ChallengeError, IndeterminateError, InputRequiredError, SchemaError } from '../../core/errors/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { yundaStatus } from './status.js';
+const PROVIDER = 'Yunda Express';
+const ZONE = 'Asia/Shanghai';
+export function normalizeYundaNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    // The domestic client's documented lengths. It routes 76/77 international
+    // identifiers to the international website instead of this consumer feed.
+    if (!/^\d{13}(?:\d{2})?$/.test(number) || /^(?:76|77)/.test(number)) {
+        throw new InputRequiredError(PROVIDER, 'number', 'Yunda direct tracking requires a domestic waybill number');
+    }
+    return number;
+}
+export function yundaEnvelope(payload) {
+    if (!isRecord(payload) || !Number.isInteger(payload.code))
+        throw new SchemaError(PROVIDER, 'Yunda returned an invalid response envelope');
+    if (payload.code !== 200) {
+        const message = clean(payload.msg, 200);
+        if (payload.code === 401 || /验证码|验证失败|校验失败|滑块|captcha/i.test(message))
+            throw new ChallengeError(PROVIDER);
+        // Even a body code of 404 can mean a generic API error or empty old history.
+        throw new IndeterminateError(PROVIDER, 'Yunda returned an inconclusive API error');
+    }
+    return payload;
+}
+function identityMap(value) {
+    // PHP encodes its empty associative maps as [] rather than {}.
+    if (Array.isArray(value) && value.length === 0)
+        return {};
+    if (!isRecord(value))
+        throw new SchemaError(PROVIDER, 'Yunda returned an invalid identity map');
+    return value;
+}
+export function parseYunda(payload, trackingNumber) {
+    const number = normalizeYundaNumber(trackingNumber);
+    const envelope = yundaEnvelope(payload);
+    if (!isRecord(envelope.data))
+        throw new SchemaError(PROVIDER);
+    const orders = identityMap(envelope.data.order);
+    const histories = identityMap(envelope.data.logistic);
+    if ([...Object.keys(orders), ...Object.keys(histories)].some(identity => identity !== number)) {
+        throw new SchemaError(PROVIDER, 'Yunda returned a different or ambiguous shipment identity');
+    }
+    const history = histories[number];
+    if (history === undefined)
+        throw new IndeterminateError(PROVIDER, 'Yunda returned no domestic history');
+    if (!isRecord(history) || !Array.isArray(history.gn) || !Array.isArray(history.gj) || history.gn.length > 1000)
+        throw new SchemaError(PROVIDER);
+    if (!history.gn.length)
+        throw new IndeterminateError(PROVIDER, 'Yunda returned no domestic scans');
+    // The official client reverses this oldest-first domestic list for display.
+    // Keep its order when a clock is absent or malformed rather than sorting it
+    // among dated events or borrowing another event's time.
+    const events = [];
+    let returning = false;
+    for (const raw of history.gn) {
+        if (!isRecord(raw) || normalizeTrackingNumber(clean(raw.mailNo, 64)) !== number) {
+            throw new SchemaError(PROVIDER, 'Yunda returned mixed or incomplete scan identities');
+        }
+        const label = clean(raw.status, 100);
+        if (!label)
+            throw new SchemaError(PROVIDER, 'Yunda returned a scan with no status');
+        const detail = clean(raw.trackRecord, 1500);
+        // An explicit return scan or sender signature establishes the leg.
+        // Instructions such as "contact us if you need to return it" do not.
+        if (/签收人(?:是|为|[:：])\s*(?:寄件人|发件人|退回)|已(?:退回|返回)(?:寄件人|发件人|寄件网点)|退回件扫描/.test(detail))
+            returning = true;
+        const mapped = yundaStatus(label);
+        const stage = returning && mapped?.stage === 'delivered' ? 'returned' : mapped?.stage;
+        const description = returning && mapped?.stage === 'delivered' ? 'Returned to the sender'
+            : returning && mapped?.stage === 'out_for_delivery' ? 'Out for delivery back to the sender'
+                : returning && mapped?.stage === 'ready_for_pickup' ? 'Ready for pickup on its way back'
+                    : mapped?.wording ?? label;
+        const clock = clean(raw.scanTm, 64);
+        const time = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(clock)
+            ? zonedTime(clock, 'yyyy-MM-dd HH:mm:ss', ZONE)?.iso : null;
+        // The bracketed city is a separate coarse location. The remaining prose
+        // includes courier phones, names and pickup/recipient addresses.
+        const location = /^【([\p{Script=Han}]{1,30}(?:市|县|区))】/u.exec(detail)?.[1];
+        events.push({ description, provider_code: label,
+            ...(time ? { time } : clock ? { provider_time_text: clock } : {}),
+            ...(location ? { location } : {}), ...(stage ? { stage } : {}),
+            ...(returning ? { provider_leg: 'return' } : {}) });
+    }
+    const seen = new Set();
+    const unique = events.reverse().filter(event => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const latest = unique[0];
+    const mapped = yundaStatus(latest.provider_code);
+    const returned = latest.stage === 'returned';
+    return { status: returned ? 'exception' : mapped?.status ?? 'unknown',
+        ...(latest.stage ? { current_stage: latest.stage } : {}),
+        timezone: ZONE, last_status_text: latest.description, last_update: latest.time ?? null,
+        ...(mapped?.stage === 'delivered' && !returned && latest.time ? { delivered_at: latest.time } : {}),
+        events: unique.slice(0, 100) };
+}

package/dist/carriers/yunda/status.d.ts

@@ -0,0 +1,4 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare const yundaStatus: (label: string) => (ClassifiedStatus & {
+    wording: string;
+}) | null;

package/dist/carriers/yunda/status.js

@@ -0,0 +1,9 @@
+// The current consumer site's status labels and its published sample history.
+const STATUSES = {
+    '已揽件': { status: 'in_transit', stage: 'accepted', wording: 'Picked up' },
+    '运输中': { status: 'in_transit', stage: 'in_transit', wording: 'In transit' },
+    '派送中': { status: 'in_transit', stage: 'out_for_delivery', wording: 'Out for delivery' },
+    '待取件': { status: 'in_transit', stage: 'ready_for_pickup', wording: 'Ready for pickup' },
+    '已签收': { status: 'delivered', stage: 'delivered', wording: 'Delivered' },
+};
+export const yundaStatus = (label) => Object.hasOwn(STATUSES, label.trim()) ? STATUSES[label.trim()] : null;

package/dist/carriers/yunda/statuses.json

@@ -0,0 +1,40 @@
+{
+  "carrier": "yunda",
+  "entries": [
+    {
+      "wording": "已揽件",
+      "language": "zh",
+      "stage": "accepted",
+      "confirmedBy": "documentation",
+      "note": "Exact domestic status label in the official consumer website."
+    },
+    {
+      "wording": "运输中",
+      "language": "zh",
+      "stage": "in_transit",
+      "confirmedBy": "documentation",
+      "note": "Exact domestic status label in the official consumer website."
+    },
+    {
+      "wording": "派送中",
+      "language": "zh",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "note": "Exact domestic status label in the official consumer website."
+    },
+    {
+      "wording": "待取件",
+      "language": "zh",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "documentation",
+      "note": "Exact domestic status label in the official consumer website."
+    },
+    {
+      "wording": "已签收",
+      "language": "zh",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "note": "Exact domestic status label in the official consumer website."
+    }
+  ]
+}

package/dist/carriers/yunexpress/adapter.d.ts

@@ -0,0 +1,20 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+import { type TrawlClient, type TrawlScrapeResponse } from '../../core/transport/index.js';
+export declare function normalizeYunExpressNumber(raw: string): string;
+export declare function yunExpressTrackingUrl(raw: string): string;
+export declare function parse(payload: unknown, trackingNumber: string): CarrierResult;
+/** A later captured reply is final; never silently reuse an earlier success. */
+export declare function parseCaptured(page: TrawlScrapeResponse, number: string): CarrierResult;
+export declare class YunExpressTracker {
+    private readonly options;
+    constructor(options?: {
+        trawl?: TrawlClient | null;
+        executablePath?: string | null;
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/yunexpress/adapter.js

@@ -0,0 +1,240 @@
+import { loadChromium } from '../../core/transport/optional.js';
+import { DateTime } from 'luxon';
+import { ChallengeError, IndeterminateError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { explicitOffsetTime, EXPLICIT_OFFSET_PATTERN } from '../../core/time/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { yunExpressStatus } from './status.js';
+const API = 'https://services.yuntrack.com/Track/Query';
+const MAX_BYTES = 1_000_000;
+let browserBusy = false;
+export function normalizeYunExpressNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^YT\d{16}$/.test(number))
+        throw new TypeError('YunExpress requires a YT parcel reference');
+    return number;
+}
+export function yunExpressTrackingUrl(raw) {
+    return `https://www.yuntrack.com/parcelTracking?id=${normalizeYunExpressNumber(raw)}`;
+}
+function eventClock(raw, offset) {
+    if (EXPLICIT_OFFSET_PATTERN.test(raw)) {
+        const parsed = explicitOffsetTime(raw);
+        if (!parsed)
+            throw new SchemaError('YunExpress', 'YunExpress returned an invalid scan time');
+        return { time: parsed.iso };
+    }
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(raw))
+        throw new SchemaError('YunExpress', 'YunExpress returned an invalid scan time');
+    const parsed = DateTime.fromISO(`${raw}${offset ?? ''}`, { setZone: true, zone: 'UTC' });
+    if (!parsed.isValid)
+        throw new SchemaError('YunExpress', 'YunExpress returned an invalid scan time');
+    const iso = parsed.toISO({ suppressMilliseconds: true, includeOffset: Boolean(offset) });
+    return offset ? { time: iso } : { local_time: iso };
+}
+export function parse(payload, trackingNumber) {
+    const number = normalizeYunExpressNumber(trackingNumber);
+    if (isRecord(payload) && [1003, 1004].includes(Number(payload.Code)))
+        throw new ChallengeError('YunExpress', 'YunExpress requires its interactive tracking verification');
+    if (!isRecord(payload) || !Array.isArray(payload.ResultList))
+        throw new SchemaError('YunExpress');
+    const matches = payload.ResultList.filter((item) => isRecord(item) && item.Id === number);
+    if (matches.length !== 1 || !isRecord(matches[0]))
+        throw new SchemaError('YunExpress', 'YunExpress returned a different or ambiguous shipment');
+    const item = matches[0];
+    if (!isRecord(item.TrackInfo) || item.TrackInfo.WaybillNumber !== number || !isRecord(item.TrackData))
+        throw new SchemaError('YunExpress', 'YunExpress returned inconsistent parcel identity');
+    const info = item.TrackInfo;
+    const groups = item.TrackData.ProcessGroupList;
+    if (!Array.isArray(groups))
+        throw new SchemaError('YunExpress');
+    if (item.Status === 0 && info.TrackingStatus === 0 && groups.length === 0
+        && info.TrackEventCount === 0 && item.TrackData.ChildCount === 0
+        && Array.isArray(info.TrackEventDetails) && info.TrackEventDetails.length === 0
+        && isRecord(info.LastTrackEvent) && info.LastTrackEvent.TrackingStatus === 0
+        && info.LastTrackEvent.ProcessDate === '' && info.LastTrackEvent.ProcessContent === ''
+        && info.LastTrackEvent.ProcessLocation === '')
+        throw new NotFoundError('YunExpress');
+    if (!groups.length)
+        throw new IndeterminateError('YunExpress', 'YunExpress returned no parcel scans');
+    if (groups.length > 500)
+        throw new SchemaError('YunExpress');
+    const last = isRecord(info.LastTrackEvent) ? info.LastTrackEvent : {};
+    const lastOffset = /^GMT([+-]\d{2}:\d{2})$/.exec(clean(last.GmtProcessTimezone, 32))?.[1];
+    const events = [];
+    const seen = new Set();
+    let scans = 0;
+    let current;
+    for (const group of groups) {
+        if (!isRecord(group) || !Array.isArray(group.ProcessDetailList) || !group.ProcessDetailList.length)
+            throw new SchemaError('YunExpress');
+        for (const raw of group.ProcessDetailList) {
+            if (!isRecord(raw) || ++scans > 500)
+                throw new SchemaError('YunExpress');
+            const content = clean(raw.ProcessContent, MAX_BYTES);
+            const divider = content.lastIndexOf('----');
+            const fullDescription = clean(divider < 0 ? content : content.slice(0, divider), MAX_BYTES);
+            const fullLocation = divider < 0 ? '' : clean(content.slice(divider + 4), MAX_BYTES);
+            const description = clean(fullDescription, 500);
+            const location = clean(fullLocation, 200);
+            if (!description)
+                throw new SchemaError('YunExpress', 'YunExpress returned an empty scan');
+            const rawTime = clean(raw.ProcessDate, 64);
+            // Only the separately described latest scan supplies a verified offset.
+            // Storage/creation timezone fields say nothing about earlier scan clocks.
+            const exactLast = rawTime === last.ProcessDate && fullDescription === clean(last.ProcessContent, MAX_BYTES)
+                && fullLocation === clean(last.ProcessLocation, MAX_BYTES);
+            const clock = eventClock(rawTime, exactLast ? lastOffset : undefined);
+            if (events.length === 0 && !exactLast)
+                throw new IndeterminateError('YunExpress', 'YunExpress latest summary does not match its first scan');
+            const key = JSON.stringify([clock, description, location]);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const classified = yunExpressStatus(description, exactLast ? last.TrackingStatus : undefined);
+            if (events.length === 0)
+                current = classified;
+            events.push({ ...clock, description, location, ...(classified ? { stage: classified.stage } : {}) });
+        }
+    }
+    if (!events.length)
+        throw new IndeterminateError('YunExpress');
+    if (Array.isArray(info.TrackEventDetails) && info.TrackEventDetails.length > scans) {
+        throw new IndeterminateError('YunExpress', 'YunExpress returned incomplete parcel history');
+    }
+    const latest = events[0];
+    const classified = current;
+    const deliveryNumber = clean(info.TrackingNumber, 64).toUpperCase();
+    const country = clean(info.DestinationCountryCode, 8).toUpperCase();
+    return { status: classified?.status ?? 'unknown', ...(classified ? { current_stage: classified.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null,
+        ...(classified?.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        ...(deliveryNumber !== number && /^[A-Z0-9]{4,40}$/.test(deliveryNumber) ? { delivery_tracking_number: deliveryNumber } : {}),
+        ...(/^[A-Z]{2}$/.test(country) ? { destination_country: country } : {}), events: events.slice(0, 100) };
+}
+/** A later captured reply is final; never silently reuse an earlier success. */
+export function parseCaptured(page, number) {
+    const capture = page.capturedResponses.filter((entry) => entry.url === API).at(-1);
+    if (!capture)
+        throw new TransportError('YunExpress', 'The browser service did not capture YunExpress history');
+    if (capture.status >= 400) {
+        if ([401, 403, 405].includes(capture.status))
+            throw new ChallengeError('YunExpress', 'YunExpress rejected the browser tracking request', { status: capture.status });
+        throw new UpstreamHttpError('YunExpress', capture.status);
+    }
+    if (capture.status !== 200 || capture.truncated || capture.error || capture.body === null || capture.body.length > MAX_BYTES)
+        throw new IndeterminateError('YunExpress', 'The browser returned incomplete YunExpress history');
+    const body = capture.base64Encoded ? Buffer.from(capture.body, 'base64').toString('utf8') : capture.body;
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch (error) {
+        throw new SchemaError('YunExpress', 'YunExpress returned unreadable tracking JSON', { cause: error });
+    }
+    return parse(payload, number);
+}
+async function localBrowser(number, executablePath, signal, timeoutMs) {
+    signal.throwIfAborted();
+    if (browserBusy)
+        throw new TransportError('YunExpress', 'The YunExpress tracking browser is busy');
+    browserBusy = true;
+    let browser;
+    let rejectHistory;
+    let resolveHistory;
+    let settled = false;
+    const history = new Promise((resolve, reject) => { resolveHistory = resolve; rejectHistory = reject; });
+    void history.catch(() => { });
+    const fail = (error) => { if (!settled) {
+        settled = true;
+        rejectHistory(error);
+    } };
+    const abort = () => { fail(signal.reason); void browser?.close().catch(() => { }); };
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        browser = await (await loadChromium("YunExpress")).launch({ executablePath, headless: true, timeout: Math.min(timeoutMs, 10_000),
+            env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '/tmp', LANG: 'en_US.UTF-8' } });
+        signal.throwIfAborted();
+        const page = await browser.newPage({ locale: 'en-US' });
+        // Request interception makes the same fresh session receive API 405.
+        // Observe response events without altering the browser's network requests.
+        page.on('response', async (response) => {
+            if (settled || response.url() !== API || response.request().method() !== 'POST')
+                return;
+            try {
+                const body = response.request().postDataJSON();
+                if (!isRecord(body) || !Array.isArray(body.NumberList) || body.NumberList.length !== 1 || body.NumberList[0] !== number)
+                    throw new SchemaError('YunExpress', 'The browser submitted a different parcel');
+                if (response.status() !== 200) {
+                    if ([401, 403, 405].includes(response.status()))
+                        throw new ChallengeError('YunExpress', 'YunExpress rejected the browser tracking request', { status: response.status() });
+                    throw new UpstreamHttpError('YunExpress', response.status());
+                }
+                if (Number(response.headers()['content-length']) > MAX_BYTES)
+                    throw new SchemaError('YunExpress', 'YunExpress returned excessive tracking data');
+                const bytes = await response.body();
+                signal.throwIfAborted();
+                if (bytes.length > MAX_BYTES)
+                    throw new SchemaError('YunExpress', 'YunExpress returned excessive tracking data');
+                const result = parse(JSON.parse(bytes.toString('utf8')), number);
+                if (!settled) {
+                    settled = true;
+                    resolveHistory(result);
+                }
+            }
+            catch (error) {
+                fail(error instanceof SyntaxError ? new SchemaError('YunExpress', 'YunExpress returned unreadable tracking JSON', { cause: error }) : error);
+            }
+        });
+        const navigation = page.goto(yunExpressTrackingUrl(number), { waitUntil: 'domcontentloaded', timeout: timeoutMs }).then((response) => {
+            if (!response || response.status() !== 200)
+                throw new TransportError('YunExpress', 'YunExpress tracking page is unavailable');
+            return history;
+        });
+        return await Promise.race([navigation, history]);
+    }
+    finally {
+        settled = true;
+        signal.removeEventListener('abort', abort);
+        try {
+            await browser?.close();
+        }
+        finally {
+            browserBusy = false;
+        }
+    }
+}
+export class YunExpressTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeYunExpressNumber(raw);
+        const budgetMs = context.budgetMs ?? 45_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('YunExpress timeout must be positive');
+        if (!this.options.trawl && !this.options.executablePath)
+            throw new ChallengeError('YunExpress', 'YunExpress requires a configured tracking browser');
+        return runSteps({ carrier: 'yunexpress', budgetMs, signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'browser', enabled: Boolean(this.options.executablePath), run: ({ signal, remainingMs }) => localBrowser(number, this.options.executablePath, signal, Math.max(1, Math.floor(remainingMs))) },
+            // Keep the local runtime primary. Service capture needs the matching
+            // decoded-response hook and is used only without local Chromium.
+            { id: 'trawl', enabled: !this.options.executablePath && Boolean(this.options.trawl), run: async ({ signal, remainingMs }) => {
+                    const timeoutMs = Math.max(1, Math.min(25_000, Math.floor(remainingMs)));
+                    const page = await this.options.trawl.scrape({ url: yunExpressTrackingUrl(number), skipHttp: true, maxTier: 2,
+                        maxTimeout: timeoutMs, captureResponses: [API], settleTimeout: 5_000 }, {
+                        provider: 'TRAWL while fetching YunExpress', timeoutMs, maxBytes: 2_000_000, fetcher: this.options.fetcher, signal
+                    });
+                    return parseCaptured(page, number);
+                } },
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new YunExpressTracker({ trawl: environment.trawl, executablePath: environment.browserExecutablePath,
+        fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'yunexpress', recordsSteps: true, steps: ['browser', 'trawl'], track: (input, context) => tracker.fetch(input.number, context) };
+};