universal-parcel-scraper 0.133.3-main.1118 → 0.134.0

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

@@ -28,8 +28,8 @@
  * then asks Asendia UK's tracker (uk.ts), which serves parcels Asendia UK
  * carries, when A1 does not know the number, fails, or holds its registration
  * alone. 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 neither tracker knows is a
+ * other subsidiaries, uses an optional browser recovery step (browser.ts).
+ * Without that service, a number neither HTTP tracker knows is a
  * not-found for this adapter only; routing then tries the universal providers
  * in the same check.
  *

package/dist/carriers/asendia/adapter.js

@@ -28,8 +28,8 @@
  * then asks Asendia UK's tracker (uk.ts), which serves parcels Asendia UK
  * carries, when A1 does not know the number, fails, or holds its registration
  * alone. 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 neither tracker knows is a
+ * other subsidiaries, uses an optional browser recovery step (browser.ts).
+ * Without that service, a number neither HTTP tracker knows is a
  * not-found for this adapter only; routing then tries the universal providers
  * in the same check.
  *
@@ -47,6 +47,8 @@ import { clean, cleanScalar, decodeText, fetchBounded, parseJsonBytes, userAgent
 import { isRecord } from '../../core/types.js';
 import { classifyAsendiaA1Event } from './status.js';
 import { AsendiaUkTracker } from './uk.js';
+import { asendiaBrowser } from './browser.js';
+import { recoverableByDefault, runSteps } from '../../core/runner/index.js';
 const PROVIDER = 'Asendia';
 const PAGE_URL = 'https://a1.asendiausa.com/tracking/';
 const SCRIPT_URL = `${PAGE_URL}js/main.js`;
@@ -485,8 +487,28 @@ export const adapter = (environment) => {
     const uk = new AsendiaUkTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     return {
         id: 'asendia',
-        // Plain HTTP against two public trackers' own requests; no second tier.
-        steps: ['direct'],
-        track: (input, context) => trackEverywhere(a1, uk, input.number, context),
+        recordsSteps: true,
+        steps: ['direct', 'trawl'],
+        track: (input, context) => {
+            const number = normalizeAsendiaA1TrackingNumber(input.number);
+            const browserEligible = !!environment.trawl && /^[A-Z0-9]{8,40}$/.test(number) && /\d/.test(number);
+            return runSteps({ carrier: 'asendia', signal: context?.signal,
+                budgetMs: context?.budgetMs ?? (browserEligible ? 65_000 : DEFAULT_BUDGET_MS), recorder: environment.recorder }, [
+                { id: 'direct', run: ({ signal, remainingMs }) => trackEverywhere(a1, uk, number, { signal, budgetMs: Math.min(DEFAULT_BUDGET_MS, browserEligible ? Math.max(1, Math.floor(remainingMs * 0.4)) : remainingMs) }) },
+                { id: 'trawl', enabled: browserEligible,
+                    recovers: error => error instanceof NotFoundError || recoverableByDefault(error),
+                    run: async ({ signal, remainingMs, previousError }) => {
+                        try {
+                            return await asendiaBrowser(environment.trawl, number, signal, remainingMs);
+                        }
+                        catch (error) {
+                            // The global portal cannot erase a failure from either HTTP source.
+                            if (error instanceof NotFoundError && !(previousError instanceof NotFoundError))
+                                throw previousError;
+                            throw error;
+                        }
+                    } },
+            ]);
+        },
     };
 };

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

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+import type { TrawlClient } from '../../core/transport/trawl.js';
+/** The portal may disclose a summary while requiring recipient verification for scans. */
+export declare function parseAsendiaGlobalResponse(payload: unknown, raw: string): CarrierResult;
+export declare function asendiaBrowser(trawl: TrawlClient, raw: string, signal: AbortSignal, remainingMs: number): Promise<CarrierResult>;

package/dist/carriers/asendia/browser.js

@@ -0,0 +1,102 @@
+import { DateTime } from 'luxon';
+import { BudgetExceededError, ChallengeError, NotFoundError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { asendiaTrackingApiUrl, asendiaTrackingUrl, normalizeAsendiaTrackingNumber } from './probe.js';
+import { classifyAsendiaStatus } from './status.js';
+const PROVIDER = 'Asendia';
+const MAX_BYTES = 1_000_000;
+/** The portal may disclose a summary while requiring recipient verification for scans. */
+export function parseAsendiaGlobalResponse(payload, raw) {
+    const number = normalizeAsendiaTrackingNumber(raw);
+    if (!isRecord(payload) || payload.context_code !== 1000 || !Array.isArray(payload.data) || payload.data.length > 5) {
+        throw new SchemaError(PROVIDER, 'Asendia returned an invalid global tracking response');
+    }
+    if (!payload.data.length)
+        throw new NotFoundError(PROVIDER);
+    const matches = payload.data.filter(row => isRecord(row) && [row.tracking_id, row.upper_tracking_id]
+        .some(value => typeof value === 'string' && value.toUpperCase() === number));
+    if (matches.length !== 1 || !isRecord(matches[0]))
+        throw new SchemaError(PROVIDER, 'Asendia returned a different or ambiguous shipment');
+    const parcel = matches[0];
+    const wording = clean(parcel.status, 300);
+    if (!wording)
+        throw new SchemaError(PROVIDER, 'Asendia returned no current parcel status');
+    if (parcel.events !== undefined && (!Array.isArray(parcel.events) || parcel.events.length > 500)) {
+        throw new SchemaError(PROVIDER, 'Asendia returned an invalid global history');
+    }
+    const scans = Array.isArray(parcel.events) ? parcel.events.slice().reverse() : [];
+    const events = [];
+    const seen = new Set();
+    for (const scan of scans) {
+        if (!isRecord(scan))
+            throw new SchemaError(PROVIDER, 'Asendia returned an invalid global scan');
+        const description = clean(scan.labelBC, 500) || clean(scan.harmonized_label, 500);
+        const stamp = clean(scan.event_time, 64);
+        if (!description || !stamp)
+            throw new SchemaError(PROVIDER, 'Asendia returned an incomplete global scan');
+        const instant = explicitOffsetTime(stamp);
+        const wall = instant ? null : DateTime.fromISO(stamp, { zone: 'UTC' });
+        if (!instant && (!wall?.isValid || !/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(stamp))) {
+            throw new SchemaError(PROVIDER, 'Asendia returned an invalid global scan clock');
+        }
+        const classified = classifyAsendiaStatus(description);
+        const event = {
+            ...(instant ? { time: instant.iso } : { local_time: wall.toFormat("yyyy-MM-dd'T'HH:mm:ss") }),
+            description, location: clean(scan.location_name, 200),
+            ...(classified.status !== 'unknown' ? { stage: classified.stage } : {}),
+        };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(event);
+        }
+    }
+    if (events.length && events.every(event => event.time))
+        events.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const current = classifyAsendiaStatus(wording.replaceAll('_', ' '));
+    const country = clean(parcel.destination_country_name, 100);
+    return {
+        status: current.status, ...(current.status !== 'unknown' ? { current_stage: current.stage } : {}),
+        last_status_text: wording, last_update: events[0]?.time ?? null,
+        ...(events[0]?.local_time ? { last_update_local: events[0].local_time } : {}),
+        ...(country ? { destination_country_name: country } : {}),
+        ...(!events.length ? { summary_only: true } : {}),
+        ...(events.length > 100 ? { history_truncated: true } : {}),
+        events: events.slice(0, 100), tracking_url: asendiaTrackingUrl(number), tracking_source: 'structured-web-response',
+    };
+}
+export async function asendiaBrowser(trawl, raw, signal, remainingMs) {
+    const number = normalizeAsendiaTrackingNumber(raw);
+    const endpoint = asendiaTrackingApiUrl();
+    const timeoutMs = Math.floor(remainingMs - 2000);
+    if (timeoutMs < 1)
+        throw new BudgetExceededError(PROVIDER, remainingMs);
+    const page = await trawl.scrape({ url: asendiaTrackingUrl(number), skipHttp: true, maxTier: 3,
+        captureResponses: [endpoint], maxTimeout: timeoutMs, settleTimeout: timeoutMs }, { provider: PROVIDER, timeoutMs, signal, requireSolved: false, captureWindow: 'last', maxBytes: 6 * MAX_BYTES });
+    signal.throwIfAborted();
+    const responses = page.capturedResponses.filter(row => row.url === endpoint && row.trackingNumberSubmitted === number);
+    const response = responses.at(-1);
+    if (!response || responses.length > 10)
+        throw new ChallengeError(PROVIDER, 'Asendia returned no matching verified tracking response');
+    if (response.status === 429)
+        throw new RateLimitedError(PROVIDER);
+    if ([400, 401, 403].includes(response.status))
+        throw new ChallengeError(PROVIDER, 'Asendia rejected browser verification');
+    if (response.status >= 400)
+        throw new UpstreamHttpError(PROVIDER, response.status);
+    if (response.status !== 200 || response.error || response.truncated || response.base64Encoded || !response.body) {
+        throw new TransportError(PROVIDER, 'Asendia returned an incomplete browser response');
+    }
+    if (Buffer.byteLength(response.body) > MAX_BYTES)
+        throw new SchemaError(PROVIDER, 'Asendia returned excessive browser data');
+    let payload;
+    try {
+        payload = JSON.parse(response.body);
+    }
+    catch {
+        throw new SchemaError(PROVIDER, 'Asendia returned invalid browser JSON');
+    }
+    return parseAsendiaGlobalResponse(payload, number);
+}

package/dist/carriers/asendia/carrier.json

@@ -24,7 +24,8 @@
     "mode": "automatic",
     "adapter": "asendia",
     "steps": [
-      "direct"
+      "direct",
+      "trawl"
     ],
     "localClocks": true
   },

package/dist/core/transport/trawl.d.ts

@@ -32,6 +32,8 @@ export interface TrawlCapturedResponse {
     error: string | null;
     /** 17TRACK's matching browser request included the supplied delivery postcode. */
     postcodeSubmitted?: boolean;
+    /** A carrier helper bound this response's request to one whole tracking number. */
+    trackingNumberSubmitted?: string;
 }
 export interface TrawlScrapeResponse {
     url: string;

package/dist/core/transport/trawl.js

@@ -79,6 +79,8 @@ function captured(value, window = 'first') {
         base64Encoded: entry.base64Encoded === true,
         error: typeof entry.error === 'string' ? entry.error : entry.error ? 'error' : null,
         ...(entry.postcodeSubmitted === true ? { postcodeSubmitted: true } : {}),
+        ...(typeof entry.trackingNumberSubmitted === 'string' && /^[A-Z0-9]{6,40}$/.test(entry.trackingNumberSubmitted)
+            ? { trackingNumberSubmitted: entry.trackingNumberSubmitted } : {}),
     }));
 }
 /**

package/dist/server/openapi.json

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

package/package.json

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