universal-parcel-scraper 0.240.0-main.1505 → 0.241.0

package/dist/carriers/china-post/adapter.d.ts

@@ -1,12 +1,16 @@
-import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type AdapterEnvironment, type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
+import type { StepRecorder } from '../../core/telemetry/index.js';
 export declare class ChinaPostTracker {
     #private;
     private readonly options;
     constructor(options?: {
         fetcher?: typeof fetch;
         userAgent?: string;
+        trawl?: AdapterEnvironment['trawl'];
+        recorder?: StepRecorder;
     });
+    direct(raw: string, context?: TrackingContext): Promise<CarrierResult>;
     fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
 }
 export declare const adapter: AdapterFactory;

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

@@ -1,8 +1,10 @@
 import { accepted, lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
-import { carrierErrorKind } from '../../core/errors/index.js';
+import { BudgetExceededError, carrierErrorKind } from '../../core/errors/index.js';
+import { recoverableByDefault, runSteps } from '../../core/runner/index.js';
 import { userAgentOf } from '../../core/transport/index.js';
 import { readChinaPostTraces } from './app.js';
 import { normalizeChinaPostNumber, parseChinaPostTraces, PROVIDER } from './parser.js';
+import { CHINA_POST_WEB, CHINA_POST_WEB_FLAG, CHINA_POST_WEB_TRACE, parseChinaPostWebPreview } from './web.js';
 const BUDGET_MS = 15_000;
 export class ChinaPostTracker {
     options;
@@ -11,23 +13,51 @@ export class ChinaPostTracker {
         this.options = options;
         this.#userAgent = userAgentOf(options.userAgent);
     }
-    async fetch(raw, context = {}) {
+    async direct(raw, context = {}) {
         const number = normalizeChinaPostNumber(raw);
         const budget = lookupBudget(context, BUDGET_MS, PROVIDER);
         const payload = await readChinaPostTraces(number, { fetcher: this.options.fetcher, userAgent: this.#userAgent,
             budget, callerSignal: context.signal });
         return parseChinaPostTraces(payload, number);
     }
+    async fetch(raw, context = {}) {
+        const number = normalizeChinaPostNumber(raw);
+        const budgetMs = context.budgetMs ?? (this.options.trawl ? 60_000 : BUDGET_MS);
+        const failed = (error, signal) => {
+            context.signal?.throwIfAborted();
+            if (signal.aborted)
+                throw new BudgetExceededError(PROVIDER, budgetMs);
+            throw error;
+        };
+        return runSteps({ carrier: 'china-post', budgetMs,
+            signal: context.signal, recorder: this.options.recorder }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => this.direct(number, { signal, budgetMs: remainingMs }).catch(error => failed(error, signal)) },
+            { id: 'trawl', enabled: !!this.options.trawl,
+                // The public web preview is anonymous even when the app asks for phone digits.
+                recovers: error => carrierErrorKind(error) === 'input_required'
+                    || (carrierErrorKind(error) !== 'indeterminate' && recoverableByDefault(error)),
+                run: async ({ signal, remainingMs }) => {
+                    const timeoutMs = Math.max(1, Math.floor(remainingMs - 2500));
+                    const page = await this.options.trawl.scrape({ url: `${CHINA_POST_WEB}?mailNo=${number}`, skipHttp: true, maxTier: 3,
+                        maxTimeout: timeoutMs, captureResponses: [CHINA_POST_WEB_FLAG, CHINA_POST_WEB_TRACE] }, { provider: PROVIDER, timeoutMs, signal, requireSolved: false, captureWindow: 'last', maxBytes: 4_000_000 }).catch(error => failed(error, signal));
+                    if (signal.aborted)
+                        failed(signal.reason, signal);
+                    return parseChinaPostWebPreview(page, number);
+                } },
+        ]);
+    }
 }
 export const adapter = (environment) => {
-    const tracker = new ChinaPostTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent });
+    const tracker = new ChinaPostTracker({ fetcher: environment.fetcher, userAgent: environment.userAgent,
+        trawl: environment.trawl, recorder: environment.recorder });
     return {
         id: 'china-post',
-        steps: ['direct'],
+        recordsSteps: true,
+        steps: ['direct', 'trawl'],
         track: (input, context) => tracker.fetch(input.number, context),
         recognize: async (number, context) => {
             try {
-                return await recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeChinaPostNumber(number)));
+                return await recognizeFromLookup(() => tracker.direct(number, context), () => accepted(() => normalizeChinaPostNumber(number)));
             }
             catch (error) {
                 // The check step asks for a contact phone's digits only about an item China Post holds;

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

@@ -16,7 +16,8 @@
     "mode": "automatic",
     "adapter": "china-post",
     "steps": [
-      "direct"
+      "direct",
+      "trawl"
     ],
     "recognition": {
       "rank": 905

package/dist/carriers/china-post/parser.d.ts

@@ -3,8 +3,7 @@ import type { CarrierResult } from '../../core/result/index.js';
 export declare const PROVIDER = "China Post";
 /**
  * S10 numbers issued in China, and ZS numbers of eleven digits. The service
- * knows ZS numbers but opens them only after a contact phone's last four
- * digits, so their lookups end at the check step.
+ * asks for phone digits on ZS numbers; the public web preview is separate.
  */
 export declare function normalizeChinaPostNumber(raw: string): string;
 export interface ChinaPostReply {

package/dist/carriers/china-post/parser.js

@@ -15,8 +15,7 @@ const GUEST_SCANS = 3;
 const ACCEPTED = '已揽收';
 /**
  * S10 numbers issued in China, and ZS numbers of eleven digits. The service
- * knows ZS numbers but opens them only after a contact phone's last four
- * digits, so their lookups end at the check step.
+ * asks for phone digits on ZS numbers; the public web preview is separate.
  */
 export function normalizeChinaPostNumber(raw) {
     const number = normalizeTrackingNumber(raw);

package/dist/carriers/china-post/web.d.ts

@@ -0,0 +1,7 @@
+import type { CarrierResult } from '../../core/result/index.js';
+import type { TrawlScrapeResponse } from '../../core/transport/index.js';
+export declare const CHINA_POST_WEB = "https://www.ems.com.cn/queryList";
+export declare const CHINA_POST_WEB_FLAG = "https://www.ems.com.cn/ems-web/trackTestQuery/getLogisticsTestFlag";
+export declare const CHINA_POST_WEB_TRACE = "https://www.ems.com.cn/ems-web/mailTrack/queryTrack";
+/** Read only the helper's identity-bound, privacy-filtered guest preview. */
+export declare function parseChinaPostWebPreview(page: TrawlScrapeResponse, number: string): CarrierResult;

package/dist/carriers/china-post/web.js

@@ -0,0 +1,80 @@
+import { DateTime } from 'luxon';
+import { ChallengeError, IndeterminateError, InputRequiredError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { isRecord } from '../../core/types.js';
+import { chinaPostDescription, PROVIDER } from './parser.js';
+import { chinaPostStatus } from './status.js';
+export const CHINA_POST_WEB = 'https://www.ems.com.cn/queryList';
+export const CHINA_POST_WEB_FLAG = 'https://www.ems.com.cn/ems-web/trackTestQuery/getLogisticsTestFlag';
+export const CHINA_POST_WEB_TRACE = 'https://www.ems.com.cn/ems-web/mailTrack/queryTrack';
+/** Read only the helper's identity-bound, privacy-filtered guest preview. */
+export function parseChinaPostWebPreview(page, number) {
+    const entries = page.capturedResponses.filter(row => [CHINA_POST_WEB_FLAG, CHINA_POST_WEB_TRACE].includes(row.url));
+    const entry = entries.at(-1);
+    if (!entry || entries.length > 10)
+        throw new ChallengeError(PROVIDER, 'China Post returned no verified guest preview');
+    if (entry.trackingNumberSubmitted !== number)
+        throw new SchemaError(PROVIDER, 'China Post browser request did not match the shipment');
+    if (entry.status === 429) {
+        const retry = entry.headers['retry-after'] ?? '';
+        const delay = /^\d+$/.test(retry) ? Number(retry) * 1000 : Date.parse(retry) - Date.now();
+        throw new RateLimitedError(PROVIDER, Number.isFinite(delay) ? Math.max(0, delay) : undefined);
+    }
+    if ([401, 403, 405, 412].includes(entry.status))
+        throw new ChallengeError(PROVIDER, 'China Post refused the guest preview');
+    if (entry.status >= 500)
+        throw new UpstreamHttpError(PROVIDER, entry.status);
+    if (entry.status !== 200)
+        throw new TransportError(PROVIDER, 'China Post guest preview is unavailable', { status: entry.status });
+    if (entry.error === 'invalid-json')
+        throw new SchemaError(PROVIDER, 'China Post returned invalid guest preview JSON');
+    if (entry.error || entry.truncated || entry.base64Encoded || entry.body === null || Buffer.byteLength(entry.body) > 1_000_000) {
+        throw new TransportError(PROVIDER, 'China Post returned an incomplete guest preview');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(entry.body);
+    }
+    catch {
+        throw new SchemaError(PROVIDER, 'China Post returned invalid guest preview JSON');
+    }
+    if (!isRecord(payload) || typeof payload.success !== 'boolean')
+        throw new SchemaError(PROVIDER, 'China Post returned an invalid guest preview');
+    if (!payload.success) {
+        if (payload.reason === 'rate_limit')
+            throw new RateLimitedError(PROVIDER);
+        if (payload.reason === 'phone')
+            throw new InputRequiredError(PROVIDER, 'recipient verification', 'China Post asks for contact phone verification');
+        if (payload.reason === 'empty')
+            throw new IndeterminateError(PROVIDER, 'China Post has no guest tracking information for this number');
+        if (payload.reason === 'verification')
+            throw new ChallengeError(PROVIDER, 'China Post refused the character verification');
+        throw new IndeterminateError(PROVIDER, 'China Post did not open the guest preview');
+    }
+    if (entry.url !== CHINA_POST_WEB_TRACE)
+        throw new ChallengeError(PROVIDER, 'China Post verification returned no tracking preview');
+    if (payload.match !== true || !Array.isArray(payload.scans) || payload.scans.length > 100) {
+        throw new SchemaError(PROVIDER, 'China Post guest preview did not match the shipment');
+    }
+    if (!payload.scans.length)
+        throw new IndeterminateError(PROVIDER, 'China Post returned no guest scans');
+    const scans = payload.scans;
+    const events = [];
+    for (const scan of [...scans].reverse()) {
+        if (!isRecord(scan) || scan.number !== number || typeof scan.time !== 'string'
+            || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?$/.test(scan.time)
+            || typeof scan.code !== 'string' || !/^[A-Z0-9_]{0,20}$/.test(scan.code) || typeof scan.state !== 'string') {
+            throw new SchemaError(PROVIDER, 'China Post returned an invalid guest scan');
+        }
+        const date = DateTime.fromISO(scan.time.replace(' ', 'T'), { zone: 'UTC' });
+        const description = chinaPostDescription('', scan.state);
+        if (!date.isValid || !description)
+            throw new SchemaError(PROVIDER, 'China Post returned an unreadable guest scan');
+        const stage = chinaPostStatus(scan.code, description)?.stage;
+        events.push({ local_time: date.toFormat("yyyy-MM-dd'T'HH:mm:ss"), description,
+            ...(scan.code ? { provider_code: scan.code } : {}), ...(stage ? { stage, stage_source: 'carrier_map' } : {}) });
+    }
+    const current = chinaPostStatus(events[0].provider_code ?? '', events[0].description ?? '');
+    return { status: current?.status ?? 'unknown', ...(current ? { current_stage: current.stage, current_stage_source: 'carrier_map' } : {}),
+        last_status_text: events[0].description, last_update: null, last_update_local: events[0].local_time,
+        history_truncated: true, events };
+}

package/dist/server/openapi.json

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

package/package.json

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