universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,30 @@
+/**
+ * AliExpress / Cainiao tracking.
+ *
+ * Cainiao's public shipment detail endpoint (`global.cainiao.com/global/
+ * detail.json`) is the same keyless JSON the consumer tracking page reads. One
+ * GET returns every requested `mailNo` as a module, so the adapter selects the
+ * module whose identifier equals the number that was asked for and refuses
+ * anything else: the endpoint happily echoes other shipments when the query is
+ * malformed, and showing a stranger's parcel would be worse than an error.
+ *
+ * A module with no status, no history and no latest trace is genuinely unknown
+ * only when `mailNoSource` is `EXTERNAL`; otherwise Cainiao is still waiting
+ * for the seller and the parcel is simply pending.
+ */
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+/** Projects one `detail.json` payload. Pure: the offline tests target this. */
+export declare function parseCainiaoTrackingResponse(value: unknown, trackingNumber: string): CarrierResult;
+export declare class CainiaoTracker {
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export declare function fetchCainiao(trackingNumber: string): Promise<CarrierResult>;
+export declare const adapter: AdapterFactory;

package/dist/carriers/aliexpress/adapter.js

@@ -0,0 +1,164 @@
+import { normalizeTrackingNumber } from '../../core/detection/normalize.js';
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { CAINIAO_ACTION_STATUS, CAINIAO_STATUS, cainiaoActionCode, cainiaoStageByStatus, } from './status.js';
+const PROVIDER = 'Cainiao';
+const UPSTREAM = 'Cainiao tracking';
+const DETAIL_URL = 'https://global.cainiao.com/global/detail.json';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_EVENTS_TO_RETURN = 20;
+const BASE_HEADERS = {
+    Accept: 'application/json, text/plain, */*',
+    'Accept-Language': 'en-US,en;q=0.9',
+    'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+};
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function recordArray(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function comparableIdentifier(value) {
+    return text(value).toLocaleUpperCase('en-US').replace(/[^A-Z0-9]/g, '');
+}
+/**
+ * The partner number Cainiao hands the parcel over with, when it publishes
+ * one. `copyRealMailNo` is the machine-readable field; `realMailNo` is display
+ * prose that sometimes wraps the same identifier in a sentence.
+ */
+function cainiaoHandoffNumber(trackingModule) {
+    const direct = normalizeTrackingNumber(text(trackingModule.copyRealMailNo));
+    if (/^(?=.*\d)[A-Z0-9]{8,30}$/.test(direct)) {
+        return direct;
+    }
+    const display = text(trackingModule.realMailNo);
+    const match = /(?<![A-Z0-9])(?=[A-Z0-9]*\d)[A-Z0-9]{8,30}(?![A-Z0-9])/i.exec(display);
+    return match?.[0].toUpperCase() ?? '';
+}
+/**
+ * A scan's time: `timeStr` is the local wall clock and `timeZone` ("GMT+2")
+ * its offset. `timeStr` alone is not UTC, and the epoch `time` field is not
+ * the instant either: it reads `timeStr` as Beijing time even for European
+ * scans, putting a morning "out for delivery" in the middle of the night
+ * (checked 2026-09-22). Without a zone the text is kept.
+ */
+function scanTime(scan) {
+    const wall = text(scan.timeStr);
+    const zone = /^(?:GMT|UTC)\s*(?:([+-])(\d{1,2})(?::?(\d{2}))?)?$/i.exec(text(scan.timeZone));
+    if (!wall || !zone)
+        return wall;
+    const offset = zone[1] ? `${zone[1]}${zone[2].padStart(2, '0')}:${zone[3] ?? '00'}` : 'Z';
+    return explicitOffsetTime(`${wall.replace(' ', 'T')}${offset}`)?.iso ?? wall;
+}
+/** Projects one `detail.json` payload. Pure: the offline tests target this. */
+export function parseCainiaoTrackingResponse(value, trackingNumber) {
+    const payload = record(value);
+    const rawModules = Array.isArray(payload.module)
+        ? payload.module
+        : Array.isArray(payload.data) ? payload.data : null;
+    if (!rawModules)
+        throw new SchemaError(PROVIDER, 'Cainiao returned an invalid tracking response');
+    const modules = recordArray(rawModules);
+    if (modules.length !== rawModules.length) {
+        throw new SchemaError(PROVIDER, 'Cainiao returned an invalid shipment entry');
+    }
+    if (modules.length === 0)
+        throw new SchemaError(PROVIDER, 'Cainiao did not return a shipment entry');
+    const requested = comparableIdentifier(trackingNumber);
+    const identified = modules.filter((module) => comparableIdentifier(module.mailNo));
+    if (identified.length === 0)
+        throw new SchemaError(PROVIDER, 'Cainiao did not return a shipment identifier');
+    const trackingModule = identified.find((module) => comparableIdentifier(module.mailNo) === requested);
+    if (!trackingModule)
+        throw new SchemaError(PROVIDER, 'Cainiao returned a different shipment');
+    const rawStatus = text(trackingModule.status);
+    const latest = record(trackingModule.latestTrace ?? trackingModule.globalCombinedLogisticsTraceDTO);
+    const rawDetails = trackingModule.detailList;
+    if (rawDetails !== undefined && !Array.isArray(rawDetails)) {
+        throw new SchemaError(PROVIDER, 'Cainiao returned invalid tracking history');
+    }
+    const details = recordArray(rawDetails);
+    if (Array.isArray(rawDetails) && details.length !== rawDetails.length) {
+        throw new SchemaError(PROVIDER, 'Cainiao returned an invalid tracking event');
+    }
+    if (Array.isArray(rawDetails)
+        && !rawStatus
+        && details.length === 0
+        && Object.keys(latest).length === 0) {
+        // Only an externally issued number can be positively unknown here; an
+        // internal one is a shipment the seller has not handed over yet.
+        if (text(trackingModule.mailNoSource).toLocaleUpperCase('en-US') === 'EXTERNAL') {
+            throw new NotFoundError(PROVIDER);
+        }
+    }
+    const status = cainiaoActionCode(latest.actionCode)
+        ? (CAINIAO_ACTION_STATUS.get(cainiaoActionCode(latest.actionCode)) ?? 'unknown')
+        : (CAINIAO_STATUS.get(rawStatus)
+            ?? (rawStatus ? 'in_transit' : details.length === 0 ? 'pending' : 'unknown'));
+    const latestAction = cainiaoActionCode(latest.actionCode);
+    const actionStage = cainiaoStageByStatus(latestAction);
+    const events = details.slice(0, MAX_EVENTS_TO_RETURN).map((event) => {
+        const code = cainiaoActionCode(event.actionCode);
+        const mapped = code ? CAINIAO_ACTION_STATUS.get(code) : undefined;
+        return {
+            time: scanTime(event),
+            location: '',
+            description: text(event.standerdDesc) || text(event.desc),
+            ...(mapped ? { stage: actionStage[mapped] ?? 'in_transit' } : {}),
+        };
+    });
+    const eta = record(trackingModule.globalEtaInfo);
+    const toMillis = (value_) => (typeof value_ === 'number' && Number.isFinite(value_) ? value_ : null);
+    const deliveryMinTime = toMillis(eta.deliveryMinTime);
+    const deliveryMaxTime = toMillis(eta.deliveryMaxTime);
+    const toDate = (millis) => (millis == null ? null : new Date(millis).toISOString().slice(0, 10));
+    const expected = toDate(deliveryMaxTime);
+    const expectedFrom = toDate(deliveryMinTime);
+    const handoff = cainiaoHandoffNumber(trackingModule);
+    const destination = text(trackingModule.destCountry).trim().slice(0, 80);
+    const deliveredAt = status === 'delivered' ? scanTime(latest) || null : null;
+    return {
+        status,
+        ...(actionStage[status] || status === 'in_transit' ? { current_stage: actionStage[status] ?? 'in_transit' } : {}),
+        last_status_text: text(latest.standerdDesc) || text(latest.desc) || rawStatus,
+        last_update: scanTime(latest) || null,
+        expected_delivery: status === 'delivered' ? null : expected,
+        ...(status === 'delivered' || expectedFrom == null || expectedFrom === expected
+            ? {}
+            : { expected_delivery_from: expectedFrom }),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        ...(handoff ? { delivery_tracking_number: handoff } : {}),
+        ...(destination ? { destination_country_name: destination } : {}),
+        events,
+    };
+}
+export class CainiaoTracker {
+    fetcher;
+    timeoutMs;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async fetch(trackingNumber) {
+        const { bytes } = await fetchBounded(`${DETAIL_URL}?${new URLSearchParams({ mailNos: trackingNumber, lang: 'en-US' })}`, { headers: { ...BASE_HEADERS, Referer: 'https://www.aliexpress.com/' } }, { provider: UPSTREAM, timeoutMs: this.timeoutMs, fetcher: this.fetcher });
+        return parseCainiaoTrackingResponse(parseJsonBytes(bytes, UPSTREAM), trackingNumber);
+    }
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export async function fetchCainiao(trackingNumber) {
+    return new CainiaoTracker().fetch(trackingNumber);
+}
+export const adapter = (environment) => {
+    const tracker = new CainiaoTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'aliexpress',
+        // One keyless GET; there is no second tier to fall back to.
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/aliexpress/carrier.json

@@ -0,0 +1,59 @@
+{
+  "id": "aliexpress",
+  "displayName": "AliExpress / Cainiao",
+  "aliases": [
+    "Cainiao",
+    "AliExpress"
+  ],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#ff4747"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "aliexpress",
+    "upstreamName": "AliExpress",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "eta",
+    "eta_window",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://global.cainiao.com/detail.htm?mailNoList={trackingNumber}",
+    "canaryUrl": "https://global.cainiao.com/",
+    "shows": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "global.cainiao.com"
+      ],
+      "params": [
+        "mailNoList"
+      ]
+    }
+  ],
+  "detection": []
+}

package/dist/carriers/aliexpress/numbers.json

@@ -0,0 +1,36 @@
+{
+  "carrier": "aliexpress",
+  "records": [
+    {
+      "number": "CNG00798678939847",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php",
+        "date": "2026-04-13"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "colis-prive"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to AliExpress / Cainiao, which no rule claims."
+    },
+    {
+      "number": "UB209300714LV",
+      "role": "quarantined",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/trackingmore100/tracking-sdk-php/blob/master/README.md"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to AliExpress / Cainiao; detection falls back to the generic postal rule."
+    }
+  ]
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Cainiao status vocabulary.
+ *
+ * Two vocabularies arrive in the same payload and they are not equivalent:
+ *
+ * - `latestTrace.actionCode` (and `detailList[].actionCode`) is the leg-level
+ *   scan code. It is the primary signal, mapped by `ACTION_STATUS` below.
+ * - The parcel-level `status` token is a coarse order state. Its vocabulary is
+ *   unestablished (real parcels carry values such as DELIVERED, CLEAR_CUSTOMS,
+ *   transport, pickup, delivered), so it is only consulted when no action code
+ *   is present.
+ *
+ * Provenance: the action map follows the prior-art client
+ * https://github.com/ha-parcel-integrations/ha-cainiao (`parcels.py`
+ * `_ACTION_MAP`, 41 codes grouped by leg, MIT).
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../core/status/index.js';
+/** Parcel-level order tokens, used only when the newest trace has no action code. */
+export declare const CAINIAO_STATUS: Map<string, CarrierStatus>;
+export declare const CAINIAO_ACTION_STATUS: Map<string, CarrierStatus>;
+/** Out-for-delivery actions that mean "waiting at a pickup point", not "on the van". */
+export declare const CAINIAO_PICKUP_ACTIONS: Set<string>;
+/** Normalize an action code: Cainiao has been seen spelling them with spaces and in lower case. */
+export declare function cainiaoActionCode(value: unknown): string;
+/**
+ * Status → stage for one lookup. The pickup distinction depends on the newest
+ * action code, so the whole table is derived from it once and then applied to
+ * the shipment and to every historical event, exactly as before the move.
+ */
+export declare function cainiaoStageByStatus(latestActionCode: string): Partial<Record<CarrierStatus, Stage>>;

package/dist/carriers/aliexpress/status.js

@@ -0,0 +1,79 @@
+/** Parcel-level order tokens, used only when the newest trace has no action code. */
+export const CAINIAO_STATUS = new Map([
+    ['WAIT_SELLER_SEND_GOODS', 'pending'],
+    ['SELLER_SEND_GOODS', 'pending'],
+    ['WAIT_BUYER_ACCEPT_GOODS', 'in_transit'],
+    ['DELIVERING', 'in_transit'],
+    ['SIGN', 'delivered'],
+    ['FAILED', 'exception'],
+    ['RETURNED', 'exception'],
+]);
+// Primary signal, from ha-cainiao parcels.py _ACTION_MAP (41 codes, grouped by
+// leg). The parcel-level `status` token vocabulary is unestablished (real
+// parcels carry DELIVERED/CLEAR_CUSTOMS/transport/pickup/delivered), so the
+// newest latestTrace.actionCode wins and the token is only a fallback.
+export const CAINIAO_ACTION_STATUS = new Map([
+    ['GWMS_ACCEPT', 'pending'],
+    ['GWMS_PACKAGE', 'pending'],
+    ['PRE_READY_TO_SHIP', 'pending'],
+    ['CONSIGN', 'pending'],
+    ['CW_INBOUND', 'in_transit'],
+    ['CW_OUTBOUND', 'in_transit'],
+    ['CW_COMMON_PROCESSING1', 'in_transit'],
+    ['PU_PICKUP_SUCCESS', 'in_transit'],
+    ['GWMS_OUTBOUND', 'in_transit'],
+    ['SC_INBOUND_SUCCESS', 'in_transit'],
+    ['SC_OUTBOUND_SUCCESS', 'in_transit'],
+    ['SC_TRANS_INBOUND_SUCCESS', 'in_transit'],
+    ['SC_TRANS_OUTBOUND_SUCCESS', 'in_transit'],
+    ['CC_EX_START', 'in_transit'],
+    ['CC_EX_SUCCESS', 'in_transit'],
+    ['LH_HO_IN_SUCCESS', 'in_transit'],
+    ['LH_HO_AIRLINE', 'in_transit'],
+    ['LH_DEPART', 'in_transit'],
+    ['LH_ARRIVE', 'in_transit'],
+    ['LH_POST_COLLECTION', 'in_transit'],
+    ['COMMON_INTRANSIT', 'in_transit'],
+    ['TD_TRANS_DEPART', 'in_transit'],
+    ['TD_TRANS_ARRIVE', 'in_transit'],
+    ['TD_TRANS_DEPART_C', 'in_transit'],
+    ['TD_TRANS_ARRIVE_C', 'in_transit'],
+    ['CC_HO_IN_SUCCESS', 'in_transit'],
+    ['CC_IM_START', 'in_transit'],
+    ['CC_IM_SUCCESS', 'in_transit'],
+    ['CC_HO_OUT_SUCCESS', 'in_transit'],
+    ['CC_IM_FAILURE', 'exception'],
+    ['CC_IM_EXCEPTION', 'exception'],
+    ['GTMS_ACCEPT', 'in_transit'],
+    ['SC_ARRIVE', 'in_transit'],
+    ['SC_DEPART', 'in_transit'],
+    ['OE_DEPART', 'in_transit'],
+    ['LAST_MILE_ASN_NOTIFY', 'in_transit'],
+    ['GTMS_DO_DEPART', 'out_for_delivery'],
+    ['GSTA_INFORM_BUYER', 'out_for_delivery'],
+    ['GTMS_WAIT_SELF_PICK', 'out_for_delivery'],
+    // Station signed, not the recipient — must never read as delivered.
+    ['GTMS_STA_SIGNED', 'out_for_delivery'],
+    ['GTMS_SIGNED', 'delivered'],
+    ['GTMS_STA_SIGN_FAILURE', 'exception'],
+    ['EXCEPTION', 'exception'],
+]);
+/** Out-for-delivery actions that mean "waiting at a pickup point", not "on the van". */
+export const CAINIAO_PICKUP_ACTIONS = new Set(['GSTA_INFORM_BUYER', 'GTMS_WAIT_SELF_PICK', 'GTMS_STA_SIGNED']);
+/** Normalize an action code: Cainiao has been seen spelling them with spaces and in lower case. */
+export function cainiaoActionCode(value) {
+    return (typeof value === 'string' ? value : '').trim().toLocaleUpperCase('en-US').replace(/\s+/g, '_');
+}
+/**
+ * Status → stage for one lookup. The pickup distinction depends on the newest
+ * action code, so the whole table is derived from it once and then applied to
+ * the shipment and to every historical event, exactly as before the move.
+ */
+export function cainiaoStageByStatus(latestActionCode) {
+    return {
+        pending: 'registered',
+        out_for_delivery: CAINIAO_PICKUP_ACTIONS.has(latestActionCode) ? 'ready_for_pickup' : 'out_for_delivery',
+        delivered: 'delivered',
+        exception: 'exception',
+    };
+}