universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/sf-express/adapter.js

@@ -0,0 +1,87 @@
+import { BudgetExceededError, ChallengeError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { normalizeSfExpressNumber, parse } from './parser.js';
+export { normalizeSfExpressNumber, parse } from './parser.js';
+const PROVIDER = 'SF Express';
+const ORIGIN = 'https://htm.sf-express.com';
+const TRANSPORT_ALLOWANCE_MS = 15_000;
+export function sfExpressTrackingUrl(raw) {
+    return `${ORIGIN}/tw/en/dynamic_function/waybill/#search/bill-number/${normalizeSfExpressNumber(raw)}`;
+}
+export function sfExpressApiUrl(raw) {
+    return `${ORIGIN}/sf-service-core-web/service/bills/${normalizeSfExpressNumber(raw)}/routes`;
+}
+function matchesCapture(url, number) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username || parsed.password || parsed.hash || `${parsed.origin}${parsed.pathname}` !== sfExpressApiUrl(number))
+            return false;
+        const allowed = new Map([['lang', 'en'], ['region', 'tw'], ['translate', ''], ['app', 'bill']]);
+        return [...parsed.searchParams].every(([key, value]) => allowed.get(key) === value && parsed.searchParams.getAll(key).length === 1);
+    }
+    catch {
+        return false;
+    }
+}
+export class SfExpressTracker {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeSfExpressNumber(raw);
+        const budgetMs = context.budgetMs ?? this.options.timeoutMs ?? 45_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > 60_000)
+            throw new TypeError('SF Express budget must be between 1 and 60000 ms');
+        context.signal?.throwIfAborted();
+        if (budgetMs <= TRANSPORT_ALLOWANCE_MS)
+            throw new BudgetExceededError(PROVIDER, budgetMs);
+        const trawl = this.options.trawl;
+        if (!trawl)
+            throw new ChallengeError(PROVIDER, 'SF Express requires the browser tracking service');
+        return runSteps({ carrier: 'sf-express', budgetMs, signal: context.signal, recorder: this.options.recorder }, [{
+                id: 'trawl', run: async ({ signal, remainingMs }) => {
+                    const timeoutMs = Math.floor(remainingMs - TRANSPORT_ALLOWANCE_MS);
+                    if (timeoutMs < 1)
+                        throw new BudgetExceededError(PROVIDER, budgetMs);
+                    const page = await trawl.scrape({ url: sfExpressTrackingUrl(number), skipHttp: true, maxTier: 3, maxTimeout: timeoutMs,
+                        captureResponses: [sfExpressApiUrl(number)], settleTimeout: Math.min(timeoutMs, 10_000),
+                    }, { provider: 'TRAWL while fetching SF Express', timeoutMs, signal, maxBytes: 6_000_000, requireSolved: false });
+                    signal.throwIfAborted();
+                    if (![2, 3].includes(page.tier) || page.statusCode !== 200)
+                        throw new TransportError(PROVIDER, 'The browser service did not load SF Express tracking');
+                    const captures = page.capturedResponses.filter((capture) => matchesCapture(capture.url, number) && capture.status !== 204);
+                    if (!captures.length || captures.length > 10)
+                        throw new TransportError(PROVIDER, 'SF Express returned no matching tracking response');
+                    const capture = captures[captures.length - 1];
+                    if (capture.status === 429) {
+                        const retry = capture.headers['retry-after'];
+                        throw new RateLimitedError(PROVIDER, retry && /^\d+$/.test(retry) ? Number(retry) * 1_000 : undefined);
+                    }
+                    if ([401, 403].includes(capture.status))
+                        throw new ChallengeError(PROVIDER);
+                    if ([404, 410].includes(capture.status))
+                        throw new TransportError(PROVIDER, 'SF Express tracking endpoint is unavailable');
+                    if (capture.status >= 400)
+                        throw new UpstreamHttpError(PROVIDER, capture.status);
+                    if (capture.status !== 200 || capture.error || capture.truncated || capture.base64Encoded || capture.body === null) {
+                        throw new TransportError(PROVIDER, 'SF Express returned an incomplete tracking response');
+                    }
+                    if (Buffer.byteLength(capture.body, 'utf8') > 1_000_000)
+                        throw new SchemaError(PROVIDER, 'SF Express returned an unexpectedly large response');
+                    let payload;
+                    try {
+                        payload = JSON.parse(capture.body);
+                    }
+                    catch {
+                        throw new SchemaError(PROVIDER, 'SF Express returned invalid tracking JSON');
+                    }
+                    return parse(payload, number);
+                },
+            }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new SfExpressTracker({ trawl: environment.trawl, recorder: environment.recorder });
+    return { id: 'sf-express', recordsSteps: true, steps: ['trawl'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/sf-express/carrier.json

@@ -0,0 +1,78 @@
+{
+  "id": "sf-express",
+  "displayName": "SF Express",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN",
+      "HK"
+    ]
+  },
+  "brand": {
+    "color": "#dc1e32"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "sf-express",
+    "steps": [
+      "trawl"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://htm.sf-express.com/tw/en/dynamic_function/waybill/#search/bill-number/{trackingNumber}",
+    "canaryUrl": "https://htm.sf-express.com/tw/en/dynamic_function/waybill/",
+    "shows": [
+      "status",
+      "history"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "provider_code"
+    ],
+    "discarded": [
+      "proof_links",
+      "contact_details",
+      "facility_identifiers",
+      "weight",
+      "unverified_estimates"
+    ],
+    "unavailable": [
+      "verified_scan_timezone"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "sf-express.com"
+      ],
+      "path": "^/.+/waybill-detail/([^/?#]+)/?$"
+    },
+    {
+      "domains": [
+        "htm.sf-express.com"
+      ],
+      "pathPattern": "^/tw/en/dynamic_function/waybill/$",
+      "fragment": "^search/bill-number/(SF\\d{13}|\\d{12})$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "sf-express-1",
+      "pattern": "^\\d{12}$",
+      "confidence": "low"
+    },
+    {
+      "id": "sf-express-2",
+      "pattern": "^SF\\d{13}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/sf-express/numbers.json

@@ -0,0 +1,66 @@
+{
+  "carrier": "sf-express",
+  "records": [
+    {
+      "number": "133938675660",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "dpd-fr",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to SF Express, which stays one candidate among several."
+    },
+    {
+      "number": "SF6047789135544",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a8f6e8514e24c45061779b6",
+        "date": "2026-08-27"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "sf-express"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to SF Express, which stays one candidate among several."
+    },
+    {
+      "number": "SF6047381042488",
+      "role": "quarantined",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "sf-express"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to SF Express, which stays one candidate among several."
+    }
+  ]
+}

package/dist/carriers/sf-express/parser.d.ts

@@ -0,0 +1,4 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeSfExpressNumber(raw: string): string;
+/** Parse the anonymous Taiwan routes endpoint, never a logged-in waybill detail. */
+export declare function parse(payload: unknown, trackingNumber: string): CarrierResult;

package/dist/carriers/sf-express/parser.js

@@ -0,0 +1,102 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { ChallengeError, IndeterminateError, InputRequiredError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { sfExpressEventStatus, sfExpressSummaryStatus } from './status.js';
+const PROVIDER = 'SF Express';
+export function normalizeSfExpressNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^(?:SF\d{13}|\d{12})$/.test(number)) {
+        throw new InputRequiredError(PROVIDER, 'number', 'SF Express requires a 12-digit number or SF followed by 13 digits');
+    }
+    return number;
+}
+function scanTime(raw) {
+    if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(raw)) {
+        throw new SchemaError(PROVIDER, 'SF Express returned an invalid scan date');
+    }
+    // This API supplies wall clocks without offsets. UTC here only validates
+    // calendar components; the returned local_time deliberately claims no zone.
+    const parsed = DateTime.fromFormat(raw, 'yyyy-MM-dd HH:mm:ss', { zone: 'UTC' });
+    if (!parsed.isValid)
+        throw new SchemaError(PROVIDER, 'SF Express returned an invalid scan date');
+    return parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+function remarkText(raw) {
+    if (typeof raw !== 'string' || !raw || raw.length > 10_000)
+        throw new SchemaError(PROVIDER, 'SF Express returned an invalid scan remark');
+    const $ = load(raw, null, false);
+    $('script, style, iframe, img, input, button, [id="opr_phone"], .route-phone, a[href^="tel:"]').remove();
+    return clean($.root().text(), 1_000);
+}
+/** Parse the anonymous Taiwan routes endpoint, never a logged-in waybill detail. */
+export function parse(payload, trackingNumber) {
+    const number = normalizeSfExpressNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER);
+    if ((payload.code === 1 && typeof payload.detailMessage === 'string' && /captcha\s+verification failure/i.test(payload.detailMessage))
+        || payload.code === 70000)
+        throw new ChallengeError(PROVIDER);
+    if (payload.code === 60000)
+        throw new ChallengeError(PROVIDER, 'SF Express restricted the tracking query');
+    if (payload.code === 500)
+        throw new IndeterminateError(PROVIDER);
+    if (payload.success !== true || payload.code !== 0 || !Array.isArray(payload.result)
+        || payload.result.length > 20 || payload.result.some((entry) => !isRecord(entry)))
+        throw new SchemaError(PROVIDER);
+    const results = payload.result.filter(isRecord).filter((entry) => entry.id === number);
+    if (results.length !== 1)
+        throw new SchemaError(PROVIDER, 'SF Express returned a different or ambiguous shipment');
+    const shipment = results[0];
+    if (!Array.isArray(shipment.routes) || !shipment.routes.length || shipment.routes.length > 500) {
+        throw new SchemaError(PROVIDER, 'SF Express returned incomplete tracking history');
+    }
+    const events = [];
+    const seen = new Set();
+    for (const raw of shipment.routes) {
+        if (!isRecord(raw))
+            throw new SchemaError(PROVIDER, 'SF Express returned an invalid scan');
+        const text = remarkText(raw.remark);
+        // The portal removes these access links from history. They are not scans,
+        // and the mere existence of a proof link does not establish delivery.
+        if (/(?:AWB Info & POD|运单资料&签收图|運單資料&簽收圖)/.test(text))
+            continue;
+        if (!text)
+            throw new SchemaError(PROVIDER, 'SF Express returned an empty scan');
+        const localTime = scanTime(raw.scanDateTime);
+        const code = clean(raw.opCode, 64);
+        const reason = clean(raw.stayWhyCode, 64);
+        if (!/^[A-Z0-9_-]{1,64}$/.test(code))
+            throw new SchemaError(PROVIDER, 'SF Express returned an invalid operation code');
+        const status = sfExpressEventStatus(code, reason);
+        const event = { local_time: localTime, provider_code: code,
+            description: status?.status === 'delivered' ? 'Delivered' : text,
+            ...(status ? { stage: status.stage } : {}),
+        };
+        const key = JSON.stringify([localTime, event.description, code, reason]);
+        if (!seen.has(key)) {
+            events.push(event);
+            seen.add(key);
+        }
+    }
+    if (!events.length)
+        throw new SchemaError(PROVIDER, 'SF Express returned no historical scans');
+    // The official frontend orders by these same wall-clock strings. Preserve
+    // that display order without claiming absolute instants across countries.
+    events.sort((a, b) => String(b.local_time).localeCompare(String(a.local_time)));
+    const latest = events[0];
+    const latestRaw = shipment.routes.filter(isRecord).find((raw) => raw.scanDateTime === String(latest.local_time).replace('T', ' ')
+        && clean(raw.opCode, 64) === latest.provider_code);
+    const state = clean(shipment.expressState, 64);
+    const summaryStatus = sfExpressSummaryStatus(state, shipment.signed === true);
+    const latestStatus = sfExpressEventStatus(String(latest.provider_code), clean(latestRaw?.stayWhyCode, 64));
+    // State 99 is broad transit: a mapped delivery-round scan is more precise.
+    const status = state === '99' ? latestStatus ?? summaryStatus : summaryStatus ?? latestStatus;
+    const summaryText = new Map([['2', 'Cancelled'], ['3', 'Forwarded'], ['4', 'Returned to sender'], ['5', 'Held'], ['6', 'Lost']]).get(state);
+    return { status: status?.status ?? 'unknown', ...(status ? { current_stage: status.stage } : {}),
+        last_status_text: status?.status === 'delivered' ? 'Delivered' : summaryText ?? latest.description,
+        last_update: null, last_update_local: latest.local_time, expected_delivery: null,
+        events: events.slice(0, 100),
+    };
+}

package/dist/carriers/sf-express/status.d.ts

@@ -0,0 +1,4 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/** Code 8000 is ambiguous without its reason; do not default it to signed. */
+export declare function sfExpressEventStatus(code: string, reason: string): ClassifiedStatus | undefined;
+export declare function sfExpressSummaryStatus(state: string, signed: boolean): ClassifiedStatus | undefined;

package/dist/carriers/sf-express/status.js

@@ -0,0 +1,28 @@
+const DELIVERED = { stage: 'delivered', status: 'delivered' };
+const TRANSIT = { stage: 'in_transit', status: 'in_transit' };
+const EXCEPTION = { stage: 'exception', status: 'exception' };
+const RETURNED = { stage: 'returned', status: 'exception' };
+const REASONS = new Map([['1', DELIVERED], ['2', EXCEPTION], ['3', TRANSIT], ['4', RETURNED], ['6', EXCEPTION]]);
+const SUMMARY = new Map([['2', EXCEPTION], ['3', TRANSIT], ['4', RETURNED], ['5', EXCEPTION], ['6', EXCEPTION], ['99', TRANSIT], ['100', DELIVERED]]);
+// The official Taiwan frontend's operation-code groups, plus codes observed in
+// its public route response. The warehouse "delivered" group means dispatched.
+const CODES = new Map([
+    ...['80', '8000_1', '980'].map((code) => [code, DELIVERED]),
+    ...['50', '54', '950'].map((code) => [code, { stage: 'accepted', status: 'in_transit' }]),
+    ...['44', '34', '122', '123', '630', '640', '83', '47', '634', '125', '204', '70_5', '70_7', '70_65']
+        .map((code) => [code, { stage: 'out_for_delivery', status: 'out_for_delivery' }]),
+    ...['14', '30', '31', '36', '105', '106', '88', '89', '205', '201', '206', '646', '202', '626']
+        .map((code) => [code, TRANSIT]),
+    ['8000_2', EXCEPTION],
+]);
+/** Code 8000 is ambiguous without its reason; do not default it to signed. */
+export function sfExpressEventStatus(code, reason) {
+    if (code === '8000') {
+        return REASONS.get(reason);
+    }
+    return CODES.get(code);
+}
+export function sfExpressSummaryStatus(state, signed) {
+    const explicit = SUMMARY.get(state);
+    return explicit ?? (signed ? DELIVERED : undefined);
+}