universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/aramex/parser.js

@@ -0,0 +1,83 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/index.js';
+import { classifyAramexStatus } from './status.js';
+export function normalizeAramexNumber(raw) {
+    const number = raw.replace(/[\s.-]/g, '');
+    if (!/^\d{11,12}$/.test(number))
+        throw new TypeError('Aramex requires an eleven- or twelve-digit shipment number');
+    return number;
+}
+export function aramexDetailUrl(html, number) {
+    const requested = normalizeAramexNumber(number);
+    const $ = load(html);
+    const matches = $('a.shipment-card').filter((_, card) => clean($(card).find('.shipment-num h5').text(), 64) === requested);
+    if (!matches.length) {
+        if ($('.track-shipment-list h5').toArray().some(e => clean($(e).text(), 300) === 'No results found with current selection, please enter a different tracking number.')) {
+            throw new NotFoundError('Aramex');
+        }
+        throw new SchemaError('Aramex', 'Aramex did not return the requested shipment card');
+    }
+    if (matches.length !== 1)
+        throw new SchemaError('Aramex', 'Aramex returned ambiguous shipment cards');
+    const url = new URL(matches.attr('href') ?? '', 'https://www.aramex.com');
+    if (url.origin !== 'https://www.aramex.com' || url.pathname !== '/track/details' || !url.searchParams.get('q') || url.username || url.password || url.hash) {
+        throw new SchemaError('Aramex', 'Aramex returned an invalid detail link');
+    }
+    return url.href;
+}
+export function aramexDetailRedirect(location, original) {
+    const bound = new URL(original);
+    const url = new URL(location, bound);
+    if (url.origin !== bound.origin || !/^\/[a-z]{2}\/en\/track\/details$/.test(url.pathname)
+        || url.search !== bound.search || url.username || url.password || url.hash) {
+        throw new SchemaError('Aramex', 'Aramex returned an invalid detail redirect');
+    }
+    return url.href;
+}
+export function parseAramex(html, number) {
+    const requested = normalizeAramexNumber(number);
+    const $ = load(html);
+    const identifiers = $('.shipment-info .shipment-num h5');
+    if (identifiers.length !== 1 || clean(identifiers.text(), 64) !== requested)
+        throw new SchemaError('Aramex', 'Aramex returned a different shipment detail');
+    const tables = $('table.collected');
+    if (tables.length !== 1 || !tables.find('th.col-activity').length)
+        throw new SchemaError('Aramex');
+    const rows = tables.find('tr');
+    if (rows.length > 500)
+        throw new SchemaError('Aramex', 'Aramex returned excessive shipment history');
+    const events = [];
+    const seen = new Set();
+    rows.each((_, row) => {
+        if (!$(row).children('td').length)
+            return;
+        if ($(row).find('td.activity').length !== 1)
+            throw new SchemaError('Aramex', 'Aramex returned an incomplete scan row');
+        const description = clean($(row).find('td.activity').text(), 500);
+        if (!description)
+            throw new SchemaError('Aramex', 'Aramex returned a scan with no description');
+        const day = clean($(row).find('.date-time .date').text(), 32);
+        const clock = clean($(row).find('.date-time .time').text(), 16);
+        // Parsing in UTC validates the calendar digits only. The resulting wall
+        // time carries no offset because this cross-border portal does not give one.
+        const clockText = [day, clock].filter(Boolean).join(' ');
+        const parsed = DateTime.fromFormat(clockText, 'dd MMM yy HH:mm', { locale: 'en', zone: 'UTC' });
+        const local = parsed.isValid ? parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) : null;
+        const location = [clean($(row).find('.addr .city').text(), 120), clean($(row).find('.addr .country').text(), 80)].filter(Boolean).join(', ');
+        const key = `${local ?? clockText}\u0000${description}\u0000${location}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const mapped = classifyAramexStatus(description);
+        events.push({ description, ...(location ? { location } : {}), ...(local ? { local_time: local } : clockText ? { provider_time_text: clockText } : {}), ...(mapped ? { stage: mapped.stage } : {}) });
+    });
+    if (!events.length)
+        throw new IndeterminateError('Aramex', 'Aramex returned no shipment history');
+    const latest = events[0];
+    const mapped = classifyAramexStatus(latest.description ?? '');
+    return { status: mapped?.status ?? 'unknown', ...(mapped ? { current_stage: mapped.stage } : {}),
+        last_status_text: latest.description, last_update: null, last_update_local: latest.local_time ?? null,
+        expected_delivery: null, events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/aramex/status.js

@@ -0,0 +1,16 @@
+const wording = {
+    'The shipment has been delivered': { status: 'delivered', stage: 'delivered' },
+    "An Aramex Delivery Champion has the shipment and is expected to reach the customer's doorstep shortly": { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    "We've attempted to deliver the shipment, but the customer was not available at the time. Not to worry, the delivery has been rescheduled": { status: 'exception', stage: 'failed_attempt' },
+    'Updated delivery address required from customer': { status: 'exception', stage: 'exception' },
+    'The shipment is currently going through customs inspection': { status: 'in_transit', stage: 'customs' },
+    'The shipment is on its way to our Aramex facility': { status: 'in_transit', stage: 'in_transit' },
+    'The shipment has arrived at the Aramex office at the destination and is being prepared for customer pickup/delivery': { status: 'in_transit', stage: 'in_transit' },
+    'The shipment has left the Aramex transit office and is now on its way to the final destination country': { status: 'in_transit', stage: 'in_transit' },
+    'The shipment has reached Aramex transit office and is on its way to the final destination office': { status: 'in_transit', stage: 'in_transit' },
+    'The shipment is being processed and on its way to the next destination': { status: 'in_transit', stage: 'in_transit' },
+    'Shipment collected from the shipper': { status: 'in_transit', stage: 'accepted' },
+};
+export function classifyAramexStatus(value) {
+    return wording[value];
+}

package/dist/carriers/aramex/statuses.json

@@ -0,0 +1,41 @@
+{
+  "carrier": "aramex",
+  "entries": [
+    {
+      "wording": "The shipment has been delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "An Aramex Delivery Champion has the shipment and is expected to reach the customer's doorstep shortly",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "Updated delivery address required from customer",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "The shipment is currently going through customs inspection",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "The shipment is on its way to our Aramex facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "Shipment collected from the shipper",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    }
+  ]
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Asendia tracking through Asendia USA's A1 platform.
+ *
+ * Protocol provenance (inspected 2026-09-22):
+ * - The official public page https://a1.asendiausa.com/tracking/ (the same
+ *   static app is served at https://a1.asendia.com/tracking/) loads
+ *   `js/main.js`, which carries the page's public client configuration: the
+ *   API base URL, a shared Basic authorization value, an `X-AsendiaOne-ApiKey`
+ *   and the default branded tracking key. Every anonymous visitor receives the
+ *   same values. They are read from that script at run time, never pinned.
+ * - The page asks `TrackingBranded/Customer?trackingKey=` for its brand, then
+ *   `TrackingBranded/Tracking?trackingKey=&trackingNumber=`. Both answer HTTP
+ *   200 with `responseStatus.responseStatusCode` 200, or 204 when nothing
+ *   matches.
+ * - Without a valid tracking key the Tracking call answers 204 "no package
+ *   data" even for a known parcel. The key is therefore validated through
+ *   Customer (204 "no customers configured" for a wrong key) before a 204 is
+ *   reported as not found, so a rotated key cannot turn every lookup into a
+ *   not-found.
+ * - Both header values are required (JSON 401 and 403 otherwise). Cloudflare
+ *   refuses a library's default User-Agent (403 "error code: 1010"); an
+ *   ordinary one is accepted, with no cookie, session or browser.
+ * - Prior art calling the same endpoint: Paylicier/Packt (MPL-2.0,
+ *   backend/src/sources/implementations/asendia.ts) and deingithub/beanstalk
+ *   (beanstalk/parcel.py).
+ *
+ * Coverage: parcels on the A1 platform only. Asendia's global portal
+ * track.asendia.com, which serves the other subsidiaries, needs a Cloudflare
+ * Turnstile token for every search and is not used here (see probe.ts). A
+ * number A1 does not know is a not-found for this adapter only; routing then
+ * tries the universal providers in the same check.
+ *
+ * Privacy: events keep their time, wording, code and city, province and
+ * country. Address lines and postal codes in `eventLocationDetails` are never
+ * read, and nothing else from the summary is copied except the destination
+ * country, weight and the declared last-mile reference.
+ */
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export interface AsendiaA1PublicConfig {
+    /** The API origin, e.g. https://a1reportapi.asendiaprod.com. */
+    baseUrl: string;
+    authorization: string;
+    apiKey: string;
+    trackingKey: string;
+}
+export declare function normalizeAsendiaA1TrackingNumber(raw: string): string;
+/** The official public page for one number. */
+export declare function asendiaA1TrackingUrl(rawTrackingNumber: string): string;
+/**
+ * Read the public client configuration from the official page's script. The
+ * values are the ones every visitor's browser sends; the default tracking key
+ * is the only GUID in the script besides the API key.
+ */
+export declare function parseAsendiaA1PublicConfig(script: string): AsendiaA1PublicConfig;
+/** Pure projection of one Tracking reply for the requested number. */
+export declare function parseAsendiaA1TrackingResponse(payload: unknown, rawTrackingNumber: string): CarrierResult;
+export interface AsendiaA1TrackerOptions {
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+    /** Wall clock in milliseconds, for the configuration cache and budgets. */
+    now?: () => number;
+    budgetMs?: number;
+}
+export declare class AsendiaA1Tracker {
+    private readonly fetcher?;
+    private readonly now;
+    private readonly budgetMs;
+    private cached;
+    private loading;
+    constructor(options?: AsendiaA1TrackerOptions);
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
+    private freshConfig;
+    /** One page read at a time; concurrent lookups share it. */
+    private loadConfig;
+    private readConfig;
+    private keyAccepted;
+    private tracking;
+    private api;
+    private requestTimeout;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/asendia/adapter.js

@@ -0,0 +1,342 @@
+import { carrierIdFromPartner } from '../../core/catalog/hints.js';
+import { BudgetExceededError, ChallengeError, IndeterminateError, NotFoundError, SchemaError, UpstreamHttpError, } from '../../core/errors/index.js';
+import { languageStageStatus, wordingStage } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean, cleanScalar, decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyAsendiaA1Event } from './status.js';
+const PROVIDER = 'Asendia';
+const PAGE_URL = 'https://a1.asendiausa.com/tracking/';
+const SCRIPT_URL = `${PAGE_URL}js/main.js`;
+const API_HOST_SUFFIXES = ['asendiaprod.com', 'asendia.io', 'asendia.com', 'asendiausa.com'];
+const USER_AGENT = 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)';
+const GUID = /[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}/gi;
+const DEFAULT_BUDGET_MS = 25_000;
+const MAX_REQUEST_MS = 10_000;
+/** The public configuration is re-read at least this often, in case it rotates. */
+const CONFIG_TTL_MS = 6 * 60 * 60_000;
+/** A not-found is only trusted when the tracking key was accepted this recently. */
+const KEY_CHECK_TTL_MS = 15 * 60_000;
+const MAX_SCRIPT_BYTES = 500_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+const POUNDS_TO_KG = 0.453_592_37;
+/** The API refused the page's public header values (JSON 401 or 403). */
+class AsendiaCredentialsError extends SchemaError {
+    constructor() {
+        super(PROVIDER, 'Asendia rejected the public tracking credentials');
+        this.name = 'AsendiaCredentialsError';
+    }
+}
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+/** Letters and digits only, upper-cased: how A1 identifiers are compared. */
+function comparable(value) {
+    return cleanScalar(value, 80).toLocaleUpperCase('en-US').replace(/[^A-Z0-9]/g, '');
+}
+export function normalizeAsendiaA1TrackingNumber(raw) {
+    const value = comparable(raw);
+    if (!/^[A-Z0-9]{6,40}$/.test(value)) {
+        throw new TypeError('Asendia tracking numbers must contain 6 to 40 ASCII letters and digits');
+    }
+    return value;
+}
+/** The official public page for one number. */
+export function asendiaA1TrackingUrl(rawTrackingNumber) {
+    const url = new URL(PAGE_URL);
+    url.searchParams.set('trackingnumber', normalizeAsendiaA1TrackingNumber(rawTrackingNumber));
+    return url.toString();
+}
+function scriptField(script, name) {
+    const values = new Set([...script.matchAll(new RegExp(`"${name}"\\s*:\\s*"([^"\\\\]{1,600})"`, 'g'))]
+        .map((match) => match[1]));
+    if (values.size !== 1)
+        throw new SchemaError(PROVIDER, `Asendia's tracking page no longer publishes ${name}`);
+    return [...values][0];
+}
+function apiOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch (error) {
+        throw new SchemaError(PROVIDER, 'Asendia published an invalid tracking API address', { cause: error });
+    }
+    const host = url.hostname.toLowerCase();
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash
+        || !['', '/'].includes(url.pathname)
+        || !API_HOST_SUFFIXES.some((suffix) => host === suffix || host.endsWith(`.${suffix}`))) {
+        throw new SchemaError(PROVIDER, 'Asendia published an unexpected tracking API address');
+    }
+    return url.origin;
+}
+/**
+ * Read the public client configuration from the official page's script. The
+ * values are the ones every visitor's browser sends; the default tracking key
+ * is the only GUID in the script besides the API key.
+ */
+export function parseAsendiaA1PublicConfig(script) {
+    const baseUrl = apiOrigin(scriptField(script, 'baseUrl'));
+    const authorization = scriptField(script, 'authorizationHeaderValue');
+    const apiKey = scriptField(script, 'a1ApiKeyHeaderValue');
+    if (!/^Basic [A-Za-z0-9+/]{8,500}={0,2}$/.test(authorization) || !new RegExp(`^${GUID.source}$`, 'i').test(apiKey)) {
+        throw new SchemaError(PROVIDER, 'Asendia published invalid tracking API credentials');
+    }
+    const keys = new Map([...script.matchAll(GUID)].map((match) => [match[0].toUpperCase(), match[0]]));
+    keys.delete(apiKey.toUpperCase());
+    if (keys.size !== 1)
+        throw new SchemaError(PROVIDER, "Asendia's tracking page no longer publishes one tracking key");
+    return { baseUrl, authorization, apiKey, trackingKey: [...keys.values()][0] };
+}
+function responseCode(payload) {
+    const code = record(payload.responseStatus).responseStatusCode;
+    return typeof code === 'number' && Number.isInteger(code) ? code : null;
+}
+function eventLocation(value) {
+    const location = record(value);
+    // Address lines and postal codes are deliberately not read.
+    return [location.city, location.province, location.countryIso2]
+        .map((part) => clean(part, 80))
+        .filter(Boolean)
+        .join(', ');
+}
+function eventCode(value) {
+    const code = cleanScalar(value, 32).toLocaleUpperCase('en-US');
+    return /^[A-Z0-9._-]{1,32}$/.test(code) ? code : '';
+}
+function weightKg(value) {
+    const match = /^(\d{1,5}(?:\.\d{1,4})?)\s*(lb|lbs|kg)$/i.exec(clean(value, 32));
+    if (!match)
+        return null;
+    const amount = Number(match[1]) * (match[2].toLowerCase() === 'kg' ? 1 : POUNDS_TO_KG);
+    return Number.isFinite(amount) && amount > 0 ? Math.round(amount * 1000) / 1000 : null;
+}
+function parseEvents(details) {
+    const parsed = [];
+    const seen = new Set();
+    details.slice(0, MAX_EVENTS_TO_INSPECT).forEach((raw, sourceIndex) => {
+        // A1 stamps every event with an explicit offset; an offset-less value is
+        // dropped rather than guessed as UTC.
+        const time = explicitOffsetTime(raw.eventOn);
+        const description = clean(raw.eventDescription, 300);
+        if (!time || !description)
+            return;
+        const code = eventCode(raw.eventCode);
+        const location = eventLocation(raw.eventLocationDetails);
+        const identity = JSON.stringify([time.iso, code, description, location]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        // Codes are only meaningful per source: USPS and other partners reuse
+        // short codes such as "10" or "B1" for unrelated scans.
+        const classified = classifyAsendiaA1Event(clean(raw.eventSource, 80), code, description);
+        parsed.push({
+            sourceIndex,
+            classified,
+            timestamp: time.timestamp,
+            event: {
+                time: time.iso,
+                location,
+                description,
+                ...(classified ? { stage: classified.stage } : {}),
+                ...(code ? { provider_code: code } : {}),
+            },
+        });
+    });
+    // A1 lists the newest event first; keep that order for equal instants.
+    parsed.sort((left, right) => right.timestamp - left.timestamp || left.sourceIndex - right.sourceIndex);
+    return parsed.slice(0, MAX_EVENTS_TO_RETURN);
+}
+/** Pure projection of one Tracking reply for the requested number. */
+export function parseAsendiaA1TrackingResponse(payload, rawTrackingNumber) {
+    const requested = normalizeAsendiaA1TrackingNumber(rawTrackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER, 'Asendia returned an invalid tracking response');
+    const code = responseCode(payload);
+    if (code === 204)
+        throw new NotFoundError(PROVIDER);
+    if (code !== 200)
+        throw new IndeterminateError(PROVIDER, `Asendia answered with tracking status ${code ?? 'none'}`);
+    const summary = record(payload.trackingBrandedSummary);
+    const original = comparable(summary.trackingNumberCustomerCarrierOriginal);
+    const customer = comparable(summary.trackingNumberCustomer);
+    const vendor = comparable(summary.trackingNumberVendor);
+    // The reply echoes nothing about the query itself: bind it through the
+    // references it reports, which A1 also accepts as lookup numbers.
+    const identities = [original, customer, vendor].filter(Boolean);
+    if (identities.length === 0)
+        throw new SchemaError(PROVIDER, 'Asendia did not identify the shipment');
+    if (!identities.includes(requested))
+        throw new SchemaError(PROVIDER, 'Asendia returned a different shipment');
+    if (!Array.isArray(payload.trackingBrandedDetail)) {
+        throw new SchemaError(PROVIDER, 'Asendia returned an invalid tracking history');
+    }
+    const parsed = parseEvents(payload.trackingBrandedDetail.filter(isRecord));
+    const events = parsed.map(({ event }) => event);
+    const latest = events[0];
+    const explicit = parsed[0]?.classified ?? null;
+    const stage = explicit?.stage ?? (latest ? wordingStage(latest.description ?? '') : null);
+    const status = explicit?.status ?? (stage ? languageStageStatus(stage) : 'unknown');
+    const partner = carrierIdFromPartner('', clean(summary.finalMileTrackingLink, 500));
+    const destination = clean(summary.destinationCountryIso2, 2).toUpperCase();
+    const weight = weightKg(summary.weight);
+    return {
+        status,
+        ...(explicit ? { current_stage: explicit.stage } : {}),
+        last_status_text: latest?.description ?? null,
+        last_update: latest?.time ?? null,
+        expected_delivery: null,
+        ...(weight !== null ? { weight_kg: weight } : {}),
+        ...(/^[A-Z]{2}$/.test(destination) ? { destination_country: destination } : {}),
+        ...(partner && partner !== 'asendia' ? { delivery_carrier: partner } : {}),
+        ...(vendor && vendor !== requested && /^[A-Z0-9]{4,40}$/.test(vendor) ? { delivery_tracking_number: vendor } : {}),
+        events,
+    };
+}
+function retryAfterMs(header) {
+    if (header === null)
+        return undefined;
+    const value = header.trim();
+    const delay = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(delay) ? Math.max(0, delay) : undefined;
+}
+export class AsendiaA1Tracker {
+    fetcher;
+    now;
+    budgetMs;
+    cached = null;
+    loading = null;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher;
+        this.now = options.now ?? Date.now;
+        this.budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
+        if (!Number.isFinite(this.budgetMs) || this.budgetMs <= 0)
+            throw new TypeError('Asendia budget must be positive');
+    }
+    async fetch(rawTrackingNumber, context = {}) {
+        const trackingNumber = normalizeAsendiaA1TrackingNumber(rawTrackingNumber);
+        const budgetMs = context.budgetMs ?? this.budgetMs;
+        const deadline = this.now() + budgetMs;
+        const request = { deadline, budgetMs, signal: context.signal };
+        let config = this.freshConfig();
+        const reused = config !== null;
+        config ??= await this.loadConfig(request);
+        let payload;
+        try {
+            payload = await this.tracking(config.value, trackingNumber, request);
+        }
+        catch (error) {
+            // Rotated public credentials: re-read the page once, then give up.
+            if (!reused || !(error instanceof AsendiaCredentialsError))
+                throw error;
+            this.cached = null;
+            config = await this.loadConfig(request);
+            payload = await this.tracking(config.value, trackingNumber, request);
+        }
+        if (responseCode(payload) === 204 && this.now() - config.keyCheckedAt > KEY_CHECK_TTL_MS) {
+            // A 204 is also what an unaccepted key produces. Confirm the key before
+            // trusting the not-found, and retry once with a re-read page if it moved.
+            if (!await this.keyAccepted(config.value, request)) {
+                this.cached = null;
+                config = await this.loadConfig(request);
+                payload = await this.tracking(config.value, trackingNumber, request);
+            }
+            else {
+                config.keyCheckedAt = this.now();
+            }
+        }
+        const result = parseAsendiaA1TrackingResponse(payload, trackingNumber);
+        result.tracking_url = asendiaA1TrackingUrl(trackingNumber);
+        result.tracking_source = 'structured-web-response';
+        return result;
+    }
+    freshConfig() {
+        return this.cached && this.now() - this.cached.loadedAt < CONFIG_TTL_MS ? this.cached : null;
+    }
+    /** One page read at a time; concurrent lookups share it. */
+    loadConfig(request) {
+        this.loading ??= this.readConfig(request).finally(() => { this.loading = null; });
+        return this.loading;
+    }
+    async readConfig(request) {
+        const { bytes } = await fetchBounded(SCRIPT_URL, {
+            headers: { Accept: '*/*', Referer: PAGE_URL, 'User-Agent': USER_AGENT },
+        }, {
+            provider: 'Asendia tracking page', timeoutMs: this.requestTimeout(request), maxBytes: MAX_SCRIPT_BYTES, fetcher: this.fetcher,
+        });
+        const value = parseAsendiaA1PublicConfig(decodeText(bytes));
+        if (!await this.keyAccepted(value, request)) {
+            throw new SchemaError(PROVIDER, "Asendia no longer accepts its tracking page's public key");
+        }
+        const now = this.now();
+        this.cached = { value, loadedAt: now, keyCheckedAt: now };
+        return this.cached;
+    }
+    async keyAccepted(config, request) {
+        const url = new URL('/api/A1/TrackingBranded/Customer', config.baseUrl);
+        url.searchParams.set('trackingKey', config.trackingKey);
+        const payload = await this.api(url, config, request, 'Asendia tracking brand');
+        const code = responseCode(payload);
+        if (code === 200 && isRecord(payload.trackingBrandedCustomer))
+            return true;
+        if (code === 204)
+            return false;
+        throw new IndeterminateError(PROVIDER, `Asendia answered the brand check with status ${code ?? 'none'}`);
+    }
+    tracking(config, trackingNumber, request) {
+        const url = new URL('/api/A1/TrackingBranded/Tracking', config.baseUrl);
+        url.searchParams.set('trackingKey', config.trackingKey);
+        url.searchParams.set('trackingNumber', trackingNumber);
+        return this.api(url, config, request, 'Asendia tracking');
+    }
+    async api(url, config, request, provider) {
+        const { response, bytes } = await fetchBounded(url, {
+            headers: {
+                Accept: 'application/json',
+                Authorization: config.authorization,
+                'X-AsendiaOne-ApiKey': config.apiKey,
+                'User-Agent': USER_AGENT,
+            },
+        }, {
+            provider, timeoutMs: this.requestTimeout(request), maxBytes: MAX_RESPONSE_BYTES, fetcher: this.fetcher,
+            allowHttpError: true,
+        });
+        const text = decodeText(bytes);
+        const payload = /^\s*\{/.test(text) ? parseJsonBytes(bytes, PROVIDER) : null;
+        // Rejections put the code at the top level instead of under responseStatus.
+        const code = isRecord(payload)
+            ? responseCode(payload) ?? responseCode({ responseStatus: payload })
+            : null;
+        if (response.status === 401 || response.status === 403 || code === 401 || code === 403) {
+            // The API's own JSON rejection means the header values moved; anything
+            // else on 401/403 is the edge refusing the client.
+            if (code === 401 || code === 403)
+                throw new AsendiaCredentialsError();
+            throw new ChallengeError(PROVIDER, 'Asendia refused the tracking request');
+        }
+        if (!response.ok) {
+            throw new UpstreamHttpError(provider, response.status, retryAfterMs(response.headers.get('retry-after')));
+        }
+        if (!isRecord(payload))
+            throw new SchemaError(PROVIDER, 'Asendia returned an invalid tracking response');
+        return payload;
+    }
+    requestTimeout(request) {
+        request.signal?.throwIfAborted();
+        const remaining = Math.floor(request.deadline - this.now());
+        if (remaining < 1)
+            throw new BudgetExceededError(PROVIDER, request.budgetMs);
+        return Math.min(MAX_REQUEST_MS, remaining);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new AsendiaA1Tracker({ fetcher: environment.fetcher });
+    return {
+        id: 'asendia',
+        // Plain HTTP against the public page's own API; no second tier.
+        steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+    };
+};

package/dist/carriers/asendia/carrier.json

@@ -0,0 +1,91 @@
+{
+  "id": "asendia",
+  "displayName": "Asendia",
+  "aliases": [
+    "Asendia Management",
+    "Asendia UK",
+    "asendia.com"
+  ],
+  "region": {
+    "countries": [
+      "FR",
+      "CH",
+      "GB",
+      "DE",
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#ef7d00"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "asendia",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "weight"
+  ],
+  "portal": {
+    "url": "https://track.asendia.com/track/{trackingNumber}",
+    "canaryUrl": "https://a1.asendiausa.com/tracking/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "weight"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "weight"
+    ],
+    "discarded": [],
+    "unavailable": [
+      "eta"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "track.asendia.com"
+      ],
+      "path": "^/track/([^/?#]+)/?$"
+    },
+    {
+      "domains": [
+        "a1.asendiausa.com",
+        "a1.asendia.com"
+      ],
+      "pathPattern": "^/tracking/?$",
+      "params": [
+        "trackingnumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "asendia-1",
+      "pattern": "^ASE[A-Z0-9]{8,37}$",
+      "confidence": "high"
+    },
+    {
+      "id": "asendia-2",
+      "pattern": "^AS\\d{9}US$",
+      "confidence": "high"
+    },
+    {
+      "id": "asendia-3",
+      "pattern": "^AHOY[A-Z0-9]{8}$",
+      "confidence": "high"
+    }
+  ]
+}