universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,101 @@
+{
+  "carrier": "singapore-post",
+  "entries": [
+    {
+      "code": "HC",
+      "wording": "Held by Custom",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "DGS",
+      "wording": "Present to Import Customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "HE",
+      "wording": "Hold item at office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "LL",
+      "wording": "Arrival at Processing Center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "AD",
+      "wording": "Arrival at Destination Post",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "DO",
+      "wording": "Despatched to overseas",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "PO",
+      "wording": "Item received by SingPost",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "PL",
+      "wording": "Further processing in progress",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "CS",
+      "wording": "Customs Inspection in Progress",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "DA",
+      "wording": "Receive item at Destination Hub",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "DP",
+      "wording": "Accepted at Drop-Off Point",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "IR",
+      "wording": "SingPost has received your order information, but not your item yet",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    }
+  ]
+}

package/dist/carriers/spee-dee/carrier.json

@@ -0,0 +1,51 @@
+{
+  "id": "spee-dee",
+  "displayName": "Spee-Dee",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#ff4734"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.speedeedelivery.com/track/?tracking={trackingNumber}",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "speedeedelivery.com"
+      ],
+      "params": [
+        "tracking"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "spee-dee-1",
+      "pattern": "^SP\\d{18}$",
+      "confidence": "high"
+    },
+    {
+      "id": "spee-dee-2",
+      "pattern": "^SP\\d{16}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/spee-dee/numbers.json

@@ -0,0 +1,55 @@
+{
+  "carrier": "spee-dee",
+  "records": [
+    {
+      "number": "SP0000000000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "expect": {
+        "carrier": "spee-dee",
+        "confidence": "high"
+      },
+      "note": "Synthetic reference following the official tracker's SP plus 16 digits format."
+    },
+    {
+      "number": "SP029692450001607639",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/speedee.json"
+      },
+      "expect": {
+        "carrier": "spee-dee",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "SP029692510000901479",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/speedee.json"
+      },
+      "expect": {
+        "carrier": "spee-dee",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "SP029692510000920746",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/speedee.json"
+      },
+      "expect": {
+        "carrier": "spee-dee",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

package/dist/carriers/speedx/carrier.json

@@ -0,0 +1,49 @@
+{
+  "id": "speedx",
+  "displayName": "SpeedX",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#1aa3ff"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://tracking.speedx.io/{trackingNumber}",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "tracking.speedx.io"
+      ],
+      "path": "^/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "speedx-1",
+      "pattern": "^SPX[A-Z]{3}\\d{12}$",
+      "confidence": "high"
+    },
+    {
+      "id": "speedx-2",
+      "pattern": "^SPX[A-Z]{3}\\d{18}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/speedx/numbers.json

@@ -0,0 +1,112 @@
+{
+  "carrier": "speedx",
+  "records": [
+    {
+      "number": "SPXIND126901671914",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aac80890d392f062ac1088b",
+        "date": "2026-09-18"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPXLAX000002601010000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-30",
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Made-up 24-character number: SPX, a three-letter hub and 18 digits."
+    },
+    {
+      "number": "SPXMIA008952609060000499",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aa98f8a65d38563d593e09f",
+        "date": "2026-09-15"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported 24-character shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPXMIA056745759994",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://es.trustpilot.com/review/speedx.io"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPXMIA056746165383",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://es.trustpilot.com/review/speedx.io"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPXMIA056746185528",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://es.trustpilot.com/review/speedx.io"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPXMIA056759629631",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://es.trustpilot.com/review/speedx.io"
+      },
+      "expect": {
+        "carrier": "speedx",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "SPX000000000000000000001",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-30",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none",
+        "not": [
+          "speedx"
+        ]
+      },
+      "note": "SPX followed only by digits, without the hub letters, must not resolve to SpeedX."
+    }
+  ]
+}

package/dist/carriers/spring-gds/adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PostNL international tracking (carrier id `spring-gds`).
+ *
+ * The folder keeps the historical `spring-gds` id for parcels and clients that
+ * already store it; the carrier is presented as PostNL everywhere else. Spring
+ * GDS is PostNL's international subsidiary and its mailingtechnology.com
+ * portal shows the same barcode (see this folder's README).
+ *
+ * `postnl.post` hands out a short-lived visitor token to anyone who asks, then
+ * accepts a batch tracking request with it. Both calls replay once after a
+ * transport failure or an HTTP 502/503/504, and an HTTP 429 only when it
+ * supplies a short, valid `Retry-After`.
+ *
+ * The response echoes the requested barcodes, so the item whose `item` equals
+ * the requested number is the only one read. PostNL answers an unknown barcode
+ * with an ordinary item that has no events and says so in `message`.
+ */
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+/** Projects one `tracking-items` payload. Pure: the offline tests target this. */
+export declare function parsePostNLTrackingResponse(value: unknown, trackingNumber: string, readAt?: Date): CarrierResult;
+export declare class PostNLTracker {
+    private readonly fetcher;
+    private readonly now;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        now?: () => Date;
+    });
+    /** A fresh visitor token per lookup: it is short-lived and keyless. */
+    private visitorToken;
+    fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export declare function fetchPostNL(trackingNumber: string): Promise<CarrierResult>;
+export declare const adapter: AdapterFactory;

package/dist/carriers/spring-gds/adapter.js

@@ -0,0 +1,212 @@
+import { DateTime } from 'luxon';
+import { IndeterminateError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { countryTimeZone, explicitOffsetTime, mislabeledWallTime, settleGuessedClocks } from '../../core/time/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { postNLStatus } from './status.js';
+const PROVIDER = 'PostNL';
+const TOKEN_URL = 'https://postnl.post/api/v1/auth/token';
+const TRACK_URL = 'https://postnl.post/api/v1/tracking-items';
+const TOKEN_TIMEOUT_MS = 10_000;
+const TRACK_TIMEOUT_MS = 15_000;
+const LOOKUP_TIMEOUT_MS = 25_000;
+const MAX_TOKEN_LENGTH = 16_384;
+const NOT_FOUND_MESSAGE = /barcode was not found/i;
+// PostNL's own records (the pre-advice, the shipper's data) name no country and
+// keep Amsterdam time. See this folder's README for the evidence.
+const HOME_ZONE = 'Europe/Amsterdam';
+// Customs and bagging records carry seven fraction digits and a real "Z".
+const PRECISE_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{4,7}Z$/;
+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)',
+};
+const SITE_HEADERS = {
+    ...BASE_HEADERS,
+    'Content-Type': 'application/json',
+    Origin: 'https://postnl.post',
+    Referer: 'https://postnl.post/',
+};
+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).trim().toLocaleUpperCase('en-US');
+}
+/** A wall clock read in `zone`, refusing DST gap shifts and repeated clocks rather than choosing an offset. */
+function wallInZone(wall, zone) {
+    const parsed = DateTime.fromISO(wall, { zone });
+    if (!parsed.isValid || parsed.toISO({ includeOffset: false }) !== wall || parsed.getPossibleOffsets().length !== 1)
+        return null;
+    const iso = parsed.toISO({ suppressMilliseconds: true });
+    return iso ? { iso, timestamp: parsed.toMillis() } : null;
+}
+/**
+ * `datetime_local` is the scan's local time although PostNL appends "Z": a
+ * Swiss scan at 09:15 local arrives as "09:15Z". Each scan names its country,
+ * except PostNL's own records: their Amsterdam reading is a guess, kept only
+ * where it fits among the dated scans around it.
+ */
+function scanClock(event) {
+    const raw = text(event.datetime_local).trim().slice(0, 64);
+    if (!raw)
+        return {};
+    if (PRECISE_UTC.test(raw))
+        return { known: explicitOffsetTime(raw), provider_time_text: raw };
+    // The observed local-clock quirk uses Z. An unexpected nonzero offset
+    // cannot be converted to UTC digits and assigned a second country offset.
+    const wall = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]00:?00)?$/.test(raw) ? mislabeledWallTime(raw) : null;
+    if (!wall)
+        return { provider_time_text: raw };
+    const local = { local_time: wall.replace(/\.000$/, '') };
+    const country = text(event.country_code).trim() || text(event.country_name).trim();
+    if (!country)
+        return { ...local, guesses: [wallInZone(wall, HOME_ZONE)] };
+    const zone = countryTimeZone(country);
+    // A country alone cannot distinguish mainland clocks from island clocks.
+    return zone && !['Europe/Madrid', 'Europe/Lisbon'].includes(zone) ? { ...local, known: wallInZone(wall, zone) } : local;
+}
+/** Projects one `tracking-items` payload. Pure: the offline tests target this. */
+export function parsePostNLTrackingResponse(value, trackingNumber, readAt = new Date()) {
+    const payload = record(value);
+    const rawItems = record(payload.data).items;
+    if (!Array.isArray(rawItems)) {
+        throw new SchemaError(PROVIDER, 'PostNL returned an invalid tracking response');
+    }
+    const items = recordArray(rawItems);
+    if (items.length !== rawItems.length) {
+        throw new SchemaError(PROVIDER, 'PostNL returned an invalid shipment entry');
+    }
+    if (items.length === 0)
+        throw new SchemaError(PROVIDER, 'PostNL did not return a shipment entry');
+    const requested = comparableIdentifier(trackingNumber);
+    const identified = items.filter((candidate) => comparableIdentifier(candidate.item));
+    if (identified.length === 0) {
+        throw new SchemaError(PROVIDER, 'PostNL did not return a shipment identifier');
+    }
+    const matches = identified.filter((candidate) => comparableIdentifier(candidate.item) === requested);
+    if (matches.length !== 1)
+        throw new SchemaError(PROVIDER, 'PostNL returned a different or ambiguous shipment');
+    const item = matches[0];
+    if (!Array.isArray(item.events)) {
+        throw new SchemaError(PROVIDER, 'PostNL returned invalid tracking history');
+    }
+    const rawEvents = recordArray(item.events);
+    if (rawEvents.length !== item.events.length) {
+        throw new SchemaError(PROVIDER, 'PostNL returned an invalid tracking event');
+    }
+    if (rawEvents.length > 500)
+        throw new SchemaError(PROVIDER, 'PostNL returned excessive tracking history');
+    if (rawEvents.length === 0 && NOT_FOUND_MESSAGE.test(text(item.message))) {
+        // The rest of `message` can carry provider prose; only the recognized
+        // phrase is used, and none of it reaches the error.
+        throw new NotFoundError(PROVIDER);
+    }
+    if (rawEvents.length === 0)
+        throw new IndeterminateError(PROVIDER);
+    const clocks = rawEvents.slice(0, 100).map(scanClock);
+    const times = settleGuessedClocks(clocks, readAt.getTime());
+    const events = rawEvents.slice(0, 100).map((event, index) => {
+        const classified = postNLStatus(event.category, event.status_description);
+        const { local_time, provider_time_text } = clocks[index];
+        return {
+            ...(times[index] ? { time: times[index].iso } : local_time ? { local_time } : provider_time_text ? { provider_time_text } : {}),
+            location: (text(event.country_name) || text(event.country_code)).slice(0, 200),
+            description: (text(event.status_description) || text(event.category)).slice(0, 500),
+            ...(classified ? { stage: classified.stage } : {}),
+        };
+    });
+    const latest = rawEvents[0] ?? {};
+    const category = text(latest.category);
+    const classified = postNLStatus(category, latest.status_description);
+    // Webshop or business name only; PostNL does not expose the recipient here.
+    const senderName = text(item.senderName ?? item.sender ?? item.title).replace(/\s+/g, ' ').trim().slice(0, 200) || null;
+    const deliveredAt = classified?.status === 'delivered' ? events[0]?.time : null;
+    const destination = text(item.destination_code).trim().toUpperCase();
+    return {
+        status: classified?.status ?? 'unknown',
+        ...(classified ? { current_stage: classified.stage } : {}),
+        last_status_text: (text(latest.status_description) || category).slice(0, 500),
+        last_update: events[0]?.time || null,
+        ...(events[0]?.local_time ? { last_update_local: events[0].local_time } : {}),
+        expected_delivery: null,
+        ...(senderName ? { sender_name: senderName } : {}),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        ...(/^[A-Z]{2}$/.test(destination) ? { destination_country: destination } : {}),
+        events,
+    };
+}
+export class PostNLTracker {
+    fetcher;
+    now;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher;
+        this.now = options.now ?? (() => new Date());
+    }
+    /** A fresh visitor token per lookup: it is short-lived and keyless. */
+    async visitorToken(signal) {
+        const { bytes } = await fetchBounded(TOKEN_URL, { method: 'POST', headers: SITE_HEADERS, body: '{}', signal }, {
+            provider: 'PostNL authentication',
+            timeoutMs: TOKEN_TIMEOUT_MS,
+            maxBytes: 50_000,
+            retryTransient: true,
+            fetcher: this.fetcher,
+        });
+        const accessToken = text(record(parseJsonBytes(bytes, 'PostNL authentication')).access_token);
+        if (!accessToken || accessToken.length > MAX_TOKEN_LENGTH) {
+            throw new SchemaError(PROVIDER, 'PostNL returned an invalid visitor token');
+        }
+        return accessToken;
+    }
+    async fetch(trackingNumber, context = {}) {
+        const budget = context.budgetMs ?? LOOKUP_TIMEOUT_MS;
+        if (!Number.isFinite(budget) || budget <= 0)
+            throw new TypeError('PostNL timeout must be positive');
+        context.signal?.throwIfAborted();
+        const signal = AbortSignal.any([AbortSignal.timeout(Math.max(1, Math.floor(budget))), ...(context.signal ? [context.signal] : [])]);
+        try {
+            const accessToken = await this.visitorToken(signal);
+            const { bytes } = await fetchBounded(TRACK_URL, {
+                method: 'POST',
+                headers: { ...SITE_HEADERS, Authorization: `Bearer ${accessToken}` },
+                body: JSON.stringify({ items: [trackingNumber], language_code: 'en' }),
+                signal,
+            }, {
+                provider: 'PostNL tracking',
+                timeoutMs: TRACK_TIMEOUT_MS,
+                maxBytes: 1_000_000,
+                retryTransient: true,
+                fetcher: this.fetcher,
+            });
+            signal.throwIfAborted();
+            return parsePostNLTrackingResponse(parseJsonBytes(bytes, 'PostNL tracking'), trackingNumber, this.now());
+        }
+        catch (error) {
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                throw new TransportError(PROVIDER, 'PostNL tracking endpoint is unavailable', { cause: error });
+            }
+            throw error;
+        }
+    }
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export async function fetchPostNL(trackingNumber) {
+    return new PostNLTracker().fetch(trackingNumber);
+}
+export const adapter = (environment) => {
+    const tracker = new PostNLTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'spring-gds',
+        // The visitor token and the lookup are one step: both are keyless HTTP on
+        // the same host, and each replays once inside the step.
+        steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+    };
+};