universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/uniuni/parser.js

@@ -0,0 +1,114 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { epochSecondsTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { uniuniStatus } from './status.js';
+const PROVIDER = 'UniUni';
+export function normalizeUniuniNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^[A-Z0-9]{8,35}$/.test(number))
+        throw new TypeError('UniUni requires an alphanumeric tracking reference');
+    return number;
+}
+/** Discovery only probes formats confirmed for individual parcels. */
+export function normalizeUniuniRecognitionNumber(raw) {
+    const number = normalizeUniuniNumber(raw);
+    if (!/^(?:UUS[A-Z0-9]{16}|UUSC\d{12}|U9999\d{11}|4C\d{9}US)$/.test(number))
+        throw new TypeError('UniUni recognition requires a supported parcel format');
+    return number;
+}
+function clock(raw) {
+    if (raw == null)
+        return {};
+    if (!isRecord(raw))
+        throw new SchemaError(PROVIDER, 'UniUni returned an invalid scan clock');
+    // dateTime.ts is corrected epoch seconds. pathTime encodes local wall-clock
+    // digits as UTC seconds and is not an instant, despite its numeric shape.
+    if (raw.ts != null) {
+        if (typeof raw.ts !== 'number' || !Number.isSafeInteger(raw.ts) || raw.ts < 1_000_000_000 || raw.ts >= 10_000_000_000) {
+            throw new SchemaError(PROVIDER, 'UniUni returned invalid corrected scan seconds');
+        }
+        const time = epochSecondsTime(raw.ts);
+        if (!time)
+            throw new SchemaError(PROVIDER, 'UniUni returned an invalid corrected scan time');
+        return { time: time.iso };
+    }
+    if (raw.localTime != null && typeof raw.localTime !== 'string')
+        throw new SchemaError(PROVIDER, 'UniUni returned an invalid local scan clock');
+    const text = clean(raw.localTime, 64);
+    if (!text)
+        return {};
+    const parsed = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text)
+        ? DateTime.fromFormat(text, 'yyyy-MM-dd HH:mm:ss', { zone: 'UTC' }) : null;
+    // UTC validates calendar digits only. Without corrected seconds, preserve
+    // the provider's clock instead of choosing an offset or borrowing a scan.
+    return parsed?.isValid && parsed.toFormat('yyyy-MM-dd HH:mm:ss') === text
+        ? { local_time: parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) }
+        : { provider_time_text: text };
+}
+export function parseUniuni(payload, rawNumber) {
+    const number = normalizeUniuniNumber(rawNumber);
+    if (!isRecord(payload) || typeof payload.status !== 'string')
+        throw new SchemaError(PROVIDER);
+    if (payload.status !== 'SUCCESS')
+        throw new IndeterminateError(PROVIDER, 'UniUni returned an inconclusive lookup response');
+    if (!isRecord(payload.data) || !Array.isArray(payload.data.valid_tno) || payload.data.valid_tno.length > 25
+        || !payload.data.valid_tno.every(isRecord) || typeof payload.data.invalid_tno !== 'string' || payload.data.invalid_tno.length > 1000) {
+        throw new SchemaError(PROVIDER);
+    }
+    const valid = payload.data.valid_tno;
+    const invalid = payload.data.invalid_tno.split(',').map(value => value.trim()).filter(Boolean);
+    if (invalid.length === 1 && invalid[0] === number && !valid.length)
+        throw new NotFoundError(PROVIDER);
+    if (!valid.length && !invalid.length)
+        throw new IndeterminateError(PROVIDER, 'UniUni returned no tracking result');
+    if (invalid.length || valid.length !== 1 || valid[0].tno !== number) {
+        throw new SchemaError(PROVIDER, 'UniUni did not return one unambiguous matching parcel');
+    }
+    const item = valid[0];
+    if (item.is_master != null && item.is_master !== true && item.is_master !== false
+        && item.is_master !== 0 && item.is_master !== 1 && item.is_master !== '0' && item.is_master !== '1') {
+        throw new SchemaError(PROVIDER, 'UniUni returned an unrecognized parcel type');
+    }
+    // A master reference can include unfinished pieces alongside a delivered
+    // one. Only an independently identified single parcel is supported here.
+    if (item.is_master === true || item.is_master === 1 || item.is_master === '1' || item.master_tno
+        || (item.orders_list !== undefined && (!Array.isArray(item.orders_list) || item.orders_list.length))) {
+        throw new IndeterminateError(PROVIDER, 'UniUni returned a multi-piece shipment');
+    }
+    if (!Array.isArray(item.spath_list) || item.spath_list.length > 500)
+        throw new SchemaError(PROVIDER);
+    const events = [];
+    const seen = new Set();
+    // The public client displays this oldest-first list in reverse. Keep that
+    // sequence when the newest clock is incomplete, including equal-time scans.
+    for (const scan of [...item.spath_list].reverse()) {
+        if (!isRecord(scan))
+            throw new SchemaError(PROVIDER, 'UniUni returned an incomplete scan');
+        const description = clean(scan.description_en, 500);
+        if (!description || typeof scan.state !== 'number' || !Number.isSafeInteger(scan.state) || scan.state < 0) {
+            throw new SchemaError(PROVIDER, 'UniUni returned a scan without status or public wording');
+        }
+        const mapped = uniuniStatus(scan.state);
+        const location = [clean(scan.city, 100), clean(scan.province, 20)].filter(Boolean).join(', ');
+        // Detailed pathInfo, addresses, coordinates, operators and POD data can
+        // contain recipient or courier information; retain the English summary.
+        const event = { description, provider_code: String(scan.state), ...clock(scan.dateTime),
+            ...(location ? { location } : {}), ...(mapped ? { stage: mapped.stage } : {}) };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(event);
+        }
+    }
+    if (!events.length)
+        throw new IndeterminateError(PROVIDER, 'UniUni returned no parcel history');
+    const latest = events[0];
+    const mapped = uniuniStatus(Number(latest.provider_code));
+    return { status: mapped?.status ?? 'unknown', ...(mapped ? { current_stage: mapped.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null, last_update_local: latest.local_time ?? null,
+        expected_delivery: null, ...(mapped?.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/uniuni/status.js

@@ -0,0 +1,16 @@
+// The official client's milestone groups distinguish delivery, transfer and
+// completed return. Failed attempts are observed individual scan states.
+const STATES = new Map([
+    [190, { status: 'pending', stage: 'registered' }],
+    [1870, { status: 'pending', stage: 'registered' }],
+    ...[199, 1910, 4010, 195, 255, 218, 219, 200].map(code => [code, { status: 'in_transit', stage: 'in_transit' }]),
+    [202, { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    [211, { status: 'exception', stage: 'failed_attempt' }],
+    ...[203, 216, 228].map(code => [code, { status: 'delivered', stage: 'delivered' }]),
+    [217, { status: 'in_transit', stage: 'in_transit' }],
+    ...[206, 207, 209, 215, 222, 229, 235].map(code => [code, { status: 'exception', stage: 'exception' }]),
+    [230, { status: 'exception', stage: 'returned' }],
+]);
+export function uniuniStatus(code) {
+    return STATES.get(code);
+}

package/dist/carriers/uniuni/statuses.json

@@ -0,0 +1,54 @@
+{
+  "carrier": "uniuni",
+  "entries": [
+    {
+      "code": "190",
+      "wording": "Order received",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "199",
+      "wording": "Gateway transit in",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "195",
+      "wording": "Gateway transit out",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "200",
+      "wording": "Arrival scan",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "202",
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "211",
+      "wording": "Failed delivery attempt, returning to the warehouse",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "203",
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/unknown/carrier.json

@@ -0,0 +1,57 @@
+{
+  "id": "unknown",
+  "displayName": "Unknown carrier",
+  "displayNames": {
+    "en": "Unknown carrier",
+    "de": "Paketdienst unbekannt",
+    "fr": "Transporteur inconnu",
+    "it": "Corriere sconosciuto",
+    "es": "Transportista desconocido",
+    "pt": "Transportadora desconhecida",
+    "pl": "Nieznany przewoźnik"
+  },
+  "aliases": [],
+  "region": {
+    "countries": []
+  },
+  "brand": {
+    "color": "#8e8e93"
+  },
+  "selectable": false,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://t.17track.net/en#nums={trackingNumber}",
+    "siteName": "17TRACK",
+    "canaryUrl": "https://parcelsapp.com/en",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "17track.net"
+      ],
+      "params": [
+        "nums"
+      ],
+      "fragment": "(?:^|&)nums=([^&]+)",
+      "detectFromNumber": true
+    },
+    {
+      "domains": [
+        "parcelsapp.com"
+      ],
+      "path": "^/(?:[a-z]{2}/)?tracking/([^/?#]+)",
+      "detectFromNumber": true
+    }
+  ],
+  "detection": []
+}

package/dist/carriers/unknown/numbers.json

@@ -0,0 +1,257 @@
+{
+  "carrier": "unknown",
+  "records": [
+    {
+      "number": "00123456",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "mondial-relay",
+          "heppner"
+        ]
+      },
+      "note": "Eight-digit string that must not resolve to a carrier."
+    },
+    {
+      "number": "01234567890123",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "dpd-fr",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "10594002378611",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "123",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Too short to be a tracking number."
+    },
+    {
+      "number": "1234567890",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "123456789012",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "dpd-fr",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "123456789012345",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "dpd-fr",
+          "yunda"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "36631000001",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "postlogistics",
+          "gls-ch",
+          "gls-fr",
+          "gls-de",
+          "blue-dart",
+          "aramex"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "76434219",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "mondial-relay",
+          "heppner"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "99112233445500000",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "99112233445575012",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "colis-prive"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "AB12CD34",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "gls-ch",
+          "gls-fr",
+          "gls-de"
+        ]
+      },
+      "note": "Shared numeric shape that must stay a suggestion rather than a carrier."
+    },
+    {
+      "number": "DELIVERY",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Plain word that must never look like a tracking number."
+    },
+    {
+      "number": "RA123456789CH",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "S10 shape with a broken check digit, so the Swiss Post rule rejects it."
+    },
+    {
+      "number": "hello",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Plain word that must never look like a tracking number."
+    }
+  ]
+}

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

@@ -0,0 +1,40 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { ChallengeError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+import { TrawlClient } from '../../core/transport/index.js';
+export declare function upsTrackingUrl(trackingNumber: string): string;
+/**
+ * Akamai rejected the session (HTTP 401/403/419/429, or a page that carries no
+ * XSRF token). It stays a distinct class because the adapter reacts to it: the
+ * cached session is refreshed once, then dropped, before the browser tier runs.
+ */
+export declare class UPSSessionRejected extends ChallengeError {
+    constructor(message: string);
+}
+/**
+ * The rendered tracking page, used when no structured answer can be had. It
+ * carries the current status and the delivery location block, never a history.
+ */
+export declare function parseUPSTrackingHtml(page: string, trackingNumber: string): CarrierResult;
+/** The structured answer of the tracking page's own status API. */
+export declare function parseUPSTrackingResponse(payload: unknown, trackingNumber: string, today?: Date): CarrierResult;
+export interface UPSTrackerOptions {
+    timeoutMs?: number;
+    directTimeoutMs?: number;
+    /** Legacy configuration seam; `trawl` is preferred. */
+    trawlUrl?: string;
+    /** The browser service, or null when none is configured. */
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class UPSTracker {
+    #private;
+    readonly timeoutMs: number;
+    readonly directTimeoutMs: number;
+    readonly trawlUrl: string;
+    constructor(options?: UPSTrackerOptions);
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;