universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/j-and-t/numbers.json

@@ -0,0 +1,90 @@
+{
+  "carrier": "j-and-t",
+  "records": [
+    {
+      "number": "888 058 657 515",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://news.detik.com/suara-pembaca/d-3988487/paket-dinyatakan-hilang-j-t-menolak-mengganti-penuh",
+        "date": "2018-04-26"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to J&T Express, which stays one candidate among several."
+    },
+    {
+      "number": "JD0587577815",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://mediakonsumen.com/2026/09/14/surat-pembaca/dugaan-pencurian-dalam-pengiriman-jt-express-paket-disayat-isi-diambil-ditutup-lakban-ulang-dan-lepas-tangan",
+        "date": "2026-09-14"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "colis-prive",
+          "j-and-t"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to J&T Express, which stays one candidate among several. Indonesian parcel."
+    },
+    {
+      "number": "JT0022543312549",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a863f91058382c7b1207adb",
+        "date": "2026-08-20"
+      },
+      "expect": {
+        "carrier": "j-and-t",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Philippine parcel."
+    },
+    {
+      "number": "JY1276193661",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://mediakonsumen.com/2026/09/13/surat-pembaca/paket-jt-mandek-40-hari-tanpa-status-dana-di-tiktok-shop-ikut-tertahan-karena-resi-tidak-diperbarui",
+        "date": "2026-09-13"
+      },
+      "expect": {
+        "carrier": "j-and-t",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Indonesian parcel."
+    },
+    {
+      "number": "JY1592273075",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://mediakonsumen.com/2026/09/22/surat-pembaca/paket-tiktok-shop-dengan-jt-express-tertahan-sejak-agustus-tanpa-kejelasan",
+        "date": "2026-09-22"
+      },
+      "expect": {
+        "carrier": "j-and-t",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Indonesian parcel."
+    }
+  ]
+}

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

@@ -0,0 +1,13 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeJapanPostNumber(raw: string): string;
+export declare function parse(html: string, trackingNumber: string): CarrierResult;
+export declare class JapanPostTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

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

@@ -0,0 +1,159 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { ChallengeError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
+import { japanPostStatus } from './status.js';
+const PROVIDER = 'Japan Post';
+const ENDPOINT = 'https://trackings.post.japanpost.jp/services/srv/search/direct';
+const MAX_RESPONSE_BYTES = 1_000_000;
+// The history header explicitly states that overseas scans use local time.
+// Resolve only these confirmed prefecture/country labels from the row itself;
+// never inherit another scan's zone or the parcel's destination.
+const EVENT_ZONES = {
+    OSAKA: 'Asia/Tokyo', KANAGAWA: 'Asia/Tokyo', JAPAN: 'Asia/Tokyo', MALTA: 'Europe/Malta',
+};
+export function normalizeJapanPostNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    // The official portal accepts domestic 11–13 digit items and international
+    // S10 references. U-prefixed customs labels are explicitly not trackable.
+    if (!/^\d{11,13}$/.test(number)
+        && (!/^[A-TV-Z][A-Z]\d{9}[A-Z]{2}$/.test(number) || !isValidS10TrackingNumber(number))) {
+        throw new InputRequiredError(PROVIDER, 'number', 'Japan Post requires a domestic tracking number or a valid tracked postal reference');
+    }
+    return number;
+}
+function wallTime(raw) {
+    const format = /^\d{2}\/\d{2}\/\d{4}$/.test(raw) ? 'MM/dd/yyyy' : 'MM/dd/yyyy HH:mm';
+    // The table explicitly labels overseas scans as local time. Validate the
+    // calendar in UTC without assigning that zone to an international event.
+    const date = DateTime.fromFormat(raw, format, { zone: 'UTC' });
+    if (!date.isValid)
+        throw new SchemaError(PROVIDER, 'Japan Post returned an invalid event date');
+    return date.toFormat(format === 'MM/dd/yyyy' ? 'yyyy-MM-dd' : "yyyy-MM-dd'T'HH:mm:ss");
+}
+function eventInstant(localTime, region) {
+    const zone = EVENT_ZONES[region.toUpperCase()];
+    if (!zone || !localTime.includes('T'))
+        return null;
+    const date = DateTime.fromISO(localTime, { zone });
+    // Luxon can shift a nonexistent spring clock forward or pick one side of
+    // an autumn fold. Neither supplies an unambiguous carrier scan instant.
+    if (!date.isValid || date.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== localTime
+        || date.getPossibleOffsets().length !== 1)
+        return null;
+    return date.toUTC().toISO({ suppressMilliseconds: true });
+}
+export function parse(html, trackingNumber) {
+    const number = normalizeJapanPostNumber(trackingNumber);
+    const $ = load(html);
+    if (/just a moment|verify.*human|captcha/i.test($('title').text())
+        || $('.g-recaptcha, .h-captcha, input[name="captcha"]').length)
+        throw new ChallengeError(PROVIDER);
+    $('script, style, noscript').remove();
+    const result = $('table[summary="照会結果"]');
+    const details = $('table[summary="配達状況詳細"]');
+    const history = $('table[summary="履歴情報"]');
+    if (details.length !== 1 || history.length !== 1) {
+        const rows = result.find('tr').filter((_, row) => $(row).children('td').length > 0);
+        const cells = rows.children('td');
+        if (!details.length && !history.length && result.length === 1 && rows.length === 1 && cells.length === 2
+            && normalizeTrackingNumber(clean(cells.eq(0).text())) === number
+            && clean(cells.eq(1).text()) === '** Your item was not found. Confirm your item number and ask at your local office.') {
+            throw new NotFoundError(PROVIDER);
+        }
+        throw new SchemaError(PROVIDER, 'Japan Post returned missing or ambiguous shipment tables');
+    }
+    if (result.length)
+        throw new SchemaError(PROVIDER, 'Japan Post returned ambiguous shipment tables');
+    const headings = details.find('th').map((_, cell) => clean($(cell).text())).get();
+    const detailRows = details.find('tr').filter((_, row) => $(row).children('td').length > 0);
+    const numberColumn = headings.indexOf('Item number');
+    if (numberColumn < 0 || headings.filter((text) => text === 'Item number').length !== 1 || detailRows.length !== 1
+        || normalizeTrackingNumber(clean(detailRows.children('td').eq(numberColumn).text())) !== number) {
+        throw new SchemaError(PROVIDER, 'Japan Post returned a different or ambiguous shipment');
+    }
+    const headers = history.find('th').map((_, cell) => clean($(cell).text())).get();
+    if (!headers[0]?.startsWith('State occurrence date')
+        || headers[1] !== 'Shipping track record' || headers[2] !== 'Details' || headers[3] !== 'Office'
+        || !['Prefecture / Country', 'Prefecture'].includes(headers[4])
+        || headers[5] !== 'ZIP code（Postal code number）' || headers.length !== 6) {
+        throw new SchemaError(PROVIDER, 'Japan Post returned an invalid history table');
+    }
+    const rows = history.find('tr').filter((_, row) => $(row).children('td').length > 0);
+    if (!rows.length || rows.length % 2 !== 0 || rows.length > 1_000) {
+        throw new SchemaError(PROVIDER, 'Japan Post returned incomplete tracking history');
+    }
+    const events = [];
+    for (let index = 0; index < rows.length; index += 2) {
+        const cells = rows.eq(index).children('td');
+        const postalCode = rows.eq(index + 1).children('td');
+        if (cells.length !== 5 || [0, 1, 2, 4].some((column) => cells.eq(column).attr('rowspan') !== '2')
+            || cells.eq(3).is('[rowspan]') || cells.filter('[colspan]').length
+            || postalCode.length !== 1 || postalCode.is('[rowspan], [colspan]')) {
+            throw new SchemaError(PROVIDER, 'Japan Post returned an invalid event row');
+        }
+        const localTime = wallTime(clean(cells.eq(0).text(), 64));
+        const description = clean(cells.eq(1).text(), 500);
+        if (!description)
+            throw new SchemaError(PROVIDER, 'Japan Post returned an empty event');
+        const region = clean(cells.eq(4).text(), 100);
+        const location = [clean(cells.eq(3).text(), 150), region].filter(Boolean).join(', ');
+        const time = eventInstant(localTime, region);
+        const status = japanPostStatus(description);
+        // The host treats `time` as an instant and applies the catalog's timezone
+        // when no offset is present. Keep unresolved wall clocks in local_time.
+        events.push({ ...(time ? { time } : {}), local_time: localTime, description,
+            ...(location ? { location } : {}), ...(status ? { stage: status.stage } : {}) });
+    }
+    // The carrier presents oldest first. Preserve its sequence when some scans
+    // have unresolved zones, rather than mixing UTC and local-clock sorting.
+    const seen = new Set();
+    const latestFirst = events.reverse().filter((event) => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const latest = latestFirst[0];
+    const status = japanPostStatus(latest.description);
+    return { status: status?.status ?? 'unknown', ...(status ? { current_stage: status.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null, last_update_local: latest.local_time, expected_delivery: null,
+        events: latestFirst.slice(0, 100) };
+}
+export class JapanPostTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeJapanPostNumber(raw);
+        const budgetMs = context.budgetMs ?? this.options.timeoutMs ?? 15_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('Japan Post timeout must be positive');
+        context.signal?.throwIfAborted();
+        const url = `${ENDPOINT}?${new URLSearchParams({ reqCodeNo1: number, locale: 'en' })}`;
+        try {
+            const { bytes } = await fetchBounded(url, {}, {
+                provider: PROVIDER, maxBytes: MAX_RESPONSE_BYTES, timeoutMs: Math.max(1, Math.floor(budgetMs)),
+                fetcher: (input, init) => (this.options.fetcher ?? fetch)(input, {
+                    ...init,
+                    signal: AbortSignal.any([...(context.signal ? [context.signal] : []), ...(init?.signal ? [init.signal] : [])]),
+                }),
+            });
+            context.signal?.throwIfAborted();
+            return parse(decodeText(bytes), number);
+        }
+        catch (error) {
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                throw new TransportError(PROVIDER, 'Japan Post tracking endpoint is unavailable', { cause: error });
+            }
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new JapanPostTracker({ fetcher: environment.fetcher });
+    return { id: 'japan-post', steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

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

@@ -0,0 +1,71 @@
+{
+  "id": "japan-post",
+  "displayName": "Japan Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "JP"
+    ]
+  },
+  "brand": {
+    "color": "#cc0000"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "japan-post",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://trackings.post.japanpost.jp/services/srv/search/direct?reqCodeNo1={trackingNumber}&locale=en",
+    "canaryUrl": "https://trackings.post.japanpost.jp/services/srv/search",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "event_details",
+      "office_postcode",
+      "office_contact_details"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "sender_name",
+      "pickup_point"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "trackings.post.japanpost.jp"
+      ],
+      "params": [
+        "reqCodeNo1",
+        "requestNo1"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "japan-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}JP$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/japan-post/numbers.json

@@ -0,0 +1,35 @@
+{
+  "carrier": "japan-post",
+  "records": [
+    {
+      "number": "CI076369983JP",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "japan-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "UL123456789JP",
+      "role": "negative",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to Japan Post, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/japan-post/status.d.ts

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function japanPostStatus(description: string): ClassifiedStatus | undefined;

package/dist/carriers/japan-post/status.js

@@ -0,0 +1,25 @@
+// Exact English tracking labels from the official Japan Post result table and
+// its tracking notices. Provenance is recorded in statuses.json.
+const STATUS = new Map([
+    ['Posting/Collection', { status: 'in_transit', stage: 'accepted' }],
+    ['En route', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at outward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Dispatch from outward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrival at inward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Item presented to import Customs', { status: 'in_transit', stage: 'customs' }],
+    ['In Customs', { status: 'in_transit', stage: 'customs' }],
+    ['Item held at inward Office of Exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Item returned from import Customs', { status: 'in_transit', stage: 'in_transit' }],
+    ['Departure from inward office of exchange', { status: 'in_transit', stage: 'in_transit' }],
+    ['Processing at delivery Post Office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Item out for physical delivery', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['Final delivery', { status: 'delivered', stage: 'delivered' }],
+    ['Arrival', { status: 'in_transit', stage: 'in_transit' }],
+    ['Dispatched from Exchange Office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Transported in bond', { status: 'in_transit', stage: 'customs' }],
+    ['Arrived in bond', { status: 'in_transit', stage: 'customs' }],
+    ['Returned to sender', { status: 'exception', stage: 'returned' }],
+]);
+export function japanPostStatus(description) {
+    return STATUS.get(description);
+}

package/dist/carriers/japan-post/statuses.json

@@ -0,0 +1,136 @@
+{
+  "carrier": "japan-post",
+  "entries": [
+    {
+      "wording": "Posting/Collection",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "En route",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Arrival at outward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Dispatch from outward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Arrival at inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Item presented to import Customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "In Customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Item held at inward Office of Exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Item returned from import Customs",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Departure from inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Processing at delivery Post Office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Item out for physical delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Final delivery",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26"
+    },
+    {
+      "wording": "Arrival",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "documentation",
+      "firstSeen": "2026-09-26",
+      "note": "Official Japan Post tracking notices: https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+    },
+    {
+      "wording": "Dispatched from Exchange Office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "documentation",
+      "firstSeen": "2026-09-26",
+      "note": "Official Japan Post tracking notices: https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+    },
+    {
+      "wording": "Transported in bond",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "documentation",
+      "firstSeen": "2026-09-26",
+      "note": "Official Japan Post tracking notices: https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+    },
+    {
+      "wording": "Arrived in bond",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "documentation",
+      "firstSeen": "2026-09-26",
+      "note": "Official Japan Post tracking notices: https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+    },
+    {
+      "wording": "Returned to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "documentation",
+      "firstSeen": "2026-09-26",
+      "note": "Official Japan Post tracking notices: https://www.post.japanpost.jp/service/send/oversea/information/ems_search_en.html"
+    }
+  ]
+}

package/dist/carriers/jd-logistics/carrier.json

@@ -0,0 +1,37 @@
+{
+  "id": "jd-logistics",
+  "displayName": "JD Logistics",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#e1251b"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.jingdonglogistics.com/Tracking",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "jd-logistics-1",
+      "pattern": "^VG\\d{11}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/jd-logistics/numbers.json

@@ -0,0 +1,19 @@
+{
+  "carrier": "jd-logistics",
+  "records": [
+    {
+      "number": "VG05778167021",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "jd-logistics",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

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

@@ -0,0 +1,12 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeKoreaPostNumber(raw: string): string;
+export declare function parse(html: string, trackingNumber: string): CarrierResult;
+export declare class KoreaPostTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;