universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/poczta-polska/statuses.json

@@ -0,0 +1,47 @@
+{
+  "carrier": "poczta-polska",
+  "entries": [
+    {
+      "code": "P_REJ_KN1",
+      "wording": "Electronic item data received",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "P_NAD",
+      "wording": "Posting/collection",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "P_WD",
+      "wording": "In delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "P_D",
+      "wording": "Final delivery",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "P_PZL",
+      "wording": "In transport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "P_ND",
+      "wording": "In delivery",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/pos-malaysia/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare function normalizePosMalaysiaTrackingNumber(raw: string): string;
+export declare function posMalaysiaTrackingUrl(rawTrackingNumber: string): string;
+export declare function parsePosMalaysiaTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare class PosMalaysiaTracker {
+    readonly timeoutMs: number;
+    readonly fetcher: typeof fetch | undefined;
+    readonly recorder: StepRecorder;
+    constructor(options?: {
+        timeoutMs?: number;
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/pos-malaysia/adapter.js

@@ -0,0 +1,199 @@
+import { randomUUID } from 'node:crypto';
+import { IndeterminateError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyPosMalaysiaStatus } from './status.js';
+// Protocol provenance:
+// - The consumer request builder is shipped by https://tracking.pos.com.my:
+//   POST https://ttu-svc.pos.com.my/api/trackandtrace/v1/request with
+//   {connote_ids: [...], culture: "en"} and a client-generated P-Request-ID
+//   header. No cookies, account, signature or browser state.
+// - Empty process_status with tracking_data:null proves no available history,
+//   not absence of a shipment. Identity binds through the echoed connote_id.
+// - Event vocabulary from the vendor's own shipped demo parcel (delivered):
+//   six process_summary values with fixed English wordings, mapped in
+//   status.ts. Only process_status "DELIVERED" is a closed overall value;
+//   anything else derives from the latest event.
+const TRACKING_ENDPOINT = 'https://ttu-svc.pos.com.my/api/trackandtrace/v1/request';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_RETURN = 20;
+function parsedTime(value) {
+    // English 12-hour wall clocks. Only a confirmed domestic route establishes
+    // this zone; relayed international scans can name another country's time.
+    return zonedTime(value, 'dd MMM yyyy, hh:mm:ss a', 'Asia/Kuala_Lumpur', { locale: 'en-US' });
+}
+export function normalizePosMalaysiaTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^(?:MYPM\d{11}|[A-Z]{2}\d{9}MY)$/.test(value)) {
+        throw new TypeError('Pos Malaysia tracking requires an MYPM barcode or MY S10 identifier');
+    }
+    return value;
+}
+export function posMalaysiaTrackingUrl(rawTrackingNumber) {
+    // Path-form deep link: the SPA route tracking/:ids picks the code up as a
+    // chip and runs the lookup automatically (verified live; ?id= and
+    // #trackingIds= do not prefill).
+    return `https://tracking.pos.com.my/tracking/${encodeURIComponent(normalizePosMalaysiaTrackingNumber(rawTrackingNumber))}`;
+}
+export function parsePosMalaysiaTrackingResponse(payload, trackingNumber) {
+    const requested = normalizePosMalaysiaTrackingNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an invalid tracking response');
+    if (payload.code !== 'S0000')
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an unsuccessful tracking response');
+    if (!Array.isArray(payload.data))
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an invalid tracking response');
+    const items = payload.data.filter(isRecord);
+    if (items.length !== payload.data.length) {
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an invalid shipment entry');
+    }
+    const matching = items.filter((candidate) => typeof candidate.connote_id === 'string' && candidate.connote_id.trim().toUpperCase() === requested);
+    if (matching.length !== 1)
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned a different or ambiguous shipment');
+    const item = matching[0];
+    const domestic = isRecord(item.sender_data) && isRecord(item.recipient_data)
+        && clean(item.sender_data.sender_country, 8).toUpperCase() === 'MY'
+        && clean(item.recipient_data.receipient_country, 8).toUpperCase() === 'MY';
+    if (!Object.hasOwn(item, 'tracking_data'))
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia omitted tracking history');
+    const rawDetails = item.tracking_data;
+    if (rawDetails !== null && !Array.isArray(rawDetails))
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned invalid tracking history');
+    if (Array.isArray(rawDetails) && rawDetails.length > 500)
+        throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned oversized tracking history');
+    const parsed = [];
+    const seen = new Set();
+    (rawDetails ?? []).forEach((rawEvent, index) => {
+        if (!isRecord(rawEvent))
+            throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an invalid scan');
+        // The official client treats Error rows as response messages, not scans.
+        if (rawEvent.type === 'Error')
+            throw new IndeterminateError('Pos Malaysia', 'Pos Malaysia returned a tracking error');
+        if (rawEvent.type !== 'Valid')
+            throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an unknown scan type');
+        const summary = clean(rawEvent.process_summary, 200);
+        const description = clean(rawEvent.process, 500) || summary;
+        if (!description)
+            throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned a scan with no status');
+        if (rawEvent.date != null && typeof rawEvent.date !== 'string')
+            throw new SchemaError('Pos Malaysia', 'Pos Malaysia returned an invalid scan clock');
+        const clock = clean(rawEvent.date, 100);
+        const time = domestic ? parsedTime(clock) : null;
+        const eventType = clean(rawEvent.event_type, 32);
+        const location = clean(rawEvent.office, 160);
+        const identity = JSON.stringify([time?.iso ?? clock, summary, description, eventType, location]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyPosMalaysiaStatus(summary);
+        parsed.push({
+            event: {
+                ...(time ? { time: time.iso } : clock ? { provider_time_text: clock } : {}),
+                // Offices are Pos Malaysia facility names (hubs, kiosks), kept coarse.
+                // Sender/recipient blocks travel alongside the item but are deliberately
+                // never retained; proof-of-delivery links and image fields are dropped.
+                location,
+                description,
+                ...(classified ? { stage: classified.stage } : {}),
+                ...(eventType ? { provider_code: eventType } : {}),
+            },
+            classified,
+            timestamp: time?.timestamp ?? null,
+            index,
+        });
+    });
+    // The source supplies current-first history. Sorting a malformed clock among
+    // valid rows would promote an older scan; keep source order in that case.
+    if (parsed.every(row => row.timestamp !== null)) {
+        parsed.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    }
+    const events = parsed.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
+    if (clean(item.process_status, 32).toLocaleUpperCase('en-US') === 'DELIVERED') {
+        const latestIsDelivered = parsed[0]?.classified?.stage === 'delivered';
+        if (!latestIsDelivered) {
+            events.unshift({ description: 'Delivered', stage: 'delivered', provider_code: 'DELIVERED', summary_snapshot: true });
+            events.length = Math.min(events.length, MAX_EVENTS_TO_RETURN);
+        }
+        return {
+            status: 'delivered',
+            current_stage: 'delivered',
+            last_status_text: latestIsDelivered ? events[0]?.description ?? 'Delivered' : 'Delivered',
+            // The overall summary carries no clock. An older movement scan cannot
+            // date delivery; only a matching delivered row provides that timestamp.
+            last_update: latestIsDelivered ? events[0]?.time ?? null : null,
+            expected_delivery: null,
+            ...(domestic ? { timezone: 'Asia/Kuala_Lumpur' } : {}),
+            events,
+        };
+    }
+    if (events.length === 0)
+        throw new IndeterminateError('Pos Malaysia', 'Pos Malaysia returned no available tracking history');
+    const latest = parsed[0];
+    return {
+        status: latest.classified?.status ?? 'unknown',
+        ...(latest.classified ? { current_stage: latest.classified.stage } : {}),
+        last_status_text: latest.event.description ?? 'Tracking information received',
+        last_update: latest.event.time ?? null,
+        expected_delivery: null,
+        ...(domestic ? { timezone: 'Asia/Kuala_Lumpur' } : {}),
+        events,
+    };
+}
+export class PosMalaysiaTracker {
+    timeoutMs;
+    fetcher;
+    recorder;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        this.recorder = options.recorder ?? NOOP_RECORDER;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Pos Malaysia timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber, context = {}) {
+        const trackingNumber = normalizePosMalaysiaTrackingNumber(rawTrackingNumber);
+        const budgetMs = context.budgetMs ?? this.timeoutMs;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('Pos Malaysia budget must be positive');
+        return runSteps({ carrier: 'pos-malaysia', budgetMs, signal: context.signal, recorder: this.recorder }, [{
+                id: 'direct', run: async ({ signal, remainingMs }) => {
+                    try {
+                        const { bytes } = await fetchBounded(TRACKING_ENDPOINT, {
+                            method: 'POST', signal,
+                            headers: {
+                                Accept: 'application/json, text/plain, */*',
+                                'Accept-Language': 'en-US,en;q=0.9',
+                                'Content-Type': 'application/json',
+                                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+                                'P-Request-ID': randomUUID(),
+                            },
+                            body: JSON.stringify({ connote_ids: [trackingNumber], culture: 'en' }),
+                        }, {
+                            provider: 'Pos Malaysia tracking', timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                            maxBytes: MAX_RESPONSE_BYTES, retryTransient: true, fetcher: this.fetcher,
+                        });
+                        return parsePosMalaysiaTrackingResponse(parseJsonBytes(bytes, 'Pos Malaysia tracking'), trackingNumber);
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                            throw new TransportError('Pos Malaysia', 'Pos Malaysia tracking endpoint is unavailable', { cause: error });
+                        }
+                        throw error;
+                    }
+                },
+            }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new PosMalaysiaTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return {
+        id: 'pos-malaysia', recordsSteps: true,
+        steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+    };
+};

package/dist/carriers/pos-malaysia/carrier.json

@@ -0,0 +1,78 @@
+{
+  "id": "pos-malaysia",
+  "displayName": "Pos Malaysia",
+  "aliases": [
+    "Pos Laju",
+    "Pos Malaysia Berhad"
+  ],
+  "region": {
+    "countries": [
+      "MY"
+    ]
+  },
+  "brand": {
+    "color": "#ed1c24"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "pos-malaysia",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://tracking.pos.com.my/tracking/{trackingNumber}",
+    "canaryUrl": "https://tracking.pos.com.my/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "signature"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code"
+    ],
+    "discarded": [
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "signature"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "tracking.pos.com.my"
+      ],
+      "path": "^/tracking/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "pos-malaysia-1",
+      "pattern": "^MYPM\\d{11}$",
+      "confidence": "high"
+    },
+    {
+      "id": "pos-malaysia-2",
+      "pattern": "^[A-Z]{2}\\d{9}MY$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/pos-malaysia/numbers.json

@@ -0,0 +1,73 @@
+{
+  "carrier": "pos-malaysia",
+  "records": [
+    {
+      "number": "LP661177776MY",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.chinapostaltracking.com/qa/item-not-delivered-157490/",
+        "date": "2026-03-23"
+      },
+      "expect": {
+        "carrier": "pos-malaysia",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "MYPM00000000015",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://api-doc.pos.com.my/"
+      },
+      "expect": {
+        "carrier": "pos-malaysia",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "MYPM00000000017",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://api-doc.pos.com.my/"
+      },
+      "expect": {
+        "carrier": "pos-malaysia",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "RR157638464MY",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "pos-malaysia",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "RR158903660MY",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "pos-malaysia",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

package/dist/carriers/pos-malaysia/status.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pos Malaysia status vocabulary.
+ *
+ * `process_summary` is the short English label on each tracking row; the longer
+ * `process` sentence next to it is display prose and is never mapped. Only the
+ * parcel-level `process_status` value "DELIVERED" is a closed overall state —
+ * everything else is derived from the latest event.
+ *
+ * Unknown summaries remain visible without inventing a movement or terminal
+ * stage. The fixed labels come from the official tracking SPA's sample data
+ * and identity-bound tracking responses.
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/** Only explicit summaries establish a stage. */
+export declare function classifyPosMalaysiaStatus(summary: string): ClassifiedStatus | null;
+/** Whether the map knows this summary, for tests and documentation. */
+export declare function isMappedPosMalaysiaSummary(summary: string): boolean;

package/dist/carriers/pos-malaysia/status.js

@@ -0,0 +1,21 @@
+const SUMMARY_STATUS = {
+    'Delivery completed': { status: 'delivered', stage: 'delivered' },
+    'Out for delivery': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'Preparing for delivery': { status: 'in_transit', stage: 'in_transit' },
+    'Sorting completed': { status: 'in_transit', stage: 'in_transit' },
+    'On the way': { status: 'in_transit', stage: 'in_transit' },
+    'Collected': { status: 'in_transit', stage: 'accepted' },
+    'Item arrived at delivery office': { status: 'in_transit', stage: 'in_transit' },
+    'Your parcel is being transported to the next facility': { status: 'in_transit', stage: 'in_transit' },
+    'Your parcel has arrived at destination facility for Processing': { status: 'in_transit', stage: 'in_transit' },
+    'Your parcel is being transported to destination country': { status: 'in_transit', stage: 'in_transit' },
+    'Your parcel has arrived at our facility for sorting': { status: 'in_transit', stage: 'in_transit' },
+};
+/** Only explicit summaries establish a stage. */
+export function classifyPosMalaysiaStatus(summary) {
+    return Object.hasOwn(SUMMARY_STATUS, summary) ? SUMMARY_STATUS[summary] : null;
+}
+/** Whether the map knows this summary, for tests and documentation. */
+export function isMappedPosMalaysiaSummary(summary) {
+    return Object.hasOwn(SUMMARY_STATUS, summary);
+}

package/dist/carriers/pos-malaysia/statuses.json

@@ -0,0 +1,17 @@
+{
+  "carrier": "pos-malaysia",
+  "entries": [
+    { "wording": "Collected", "language": "en", "stage": "accepted", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "wording": "On the way", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "wording": "Sorting completed", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "wording": "Preparing for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "wording": "Out for delivery", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "wording": "Delivery completed", "language": "en", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "process_summary on the vendor's own shipped demo parcel." },
+    { "code": "DELIVERED", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-09-10", "note": "Parcel-level process_status, not an event summary: the only closed overall value; it wins even with no event rows." },
+    { "wording": "Item arrived at delivery office", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-28" },
+    { "wording": "Your parcel is being transported to the next facility", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-28" },
+    { "wording": "Your parcel has arrived at destination facility for Processing", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-28" },
+    { "wording": "Your parcel is being transported to destination country", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-28" },
+    { "wording": "Your parcel has arrived at our facility for sorting", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-28" }
+  ]
+}

package/dist/carriers/poste-italiane/adapter.d.ts

@@ -0,0 +1,15 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizePosteItalianeTrackingNumber(raw: string): string;
+export declare function posteItalianeTrackingUrl(rawTrackingNumber: string): string;
+export declare function parsePosteItalianeTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare class PosteItalianeTracker {
+    readonly timeoutMs: number;
+    readonly fetcher: typeof fetch | undefined;
+    constructor(options?: {
+        timeoutMs?: number;
+        fetcher?: typeof fetch;
+    });
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;