universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/ukrposhta/parser.js

@@ -0,0 +1,130 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
+import { ChallengeError, IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/text.js';
+import { isRecord } from '../../core/types.js';
+import { ukrposhtaReturnCue, ukrposhtaStatus } from './status.js';
+const PROVIDER = 'ukrposhta';
+const MAX_SCANS = 500;
+export function normalizeUkrposhtaNumber(raw) {
+    const number = raw.trim().replace(/[\s-]+/g, '').toUpperCase();
+    if (/^\d{13}$/.test(number) || isValidS10TrackingNumber(number))
+        return number;
+    throw new TypeError('Ukrposhta requires a 13-digit domestic or valid S10 postal reference');
+}
+function text(value, field, required = false) {
+    if (value != null && typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `Ukrposhta returned an invalid ${field}`);
+    const result = clean(value, 300);
+    if (required && !result)
+        throw new SchemaError(PROVIDER, `Ukrposhta omitted ${field}`);
+    return result;
+}
+function envelope(value) {
+    if (!isRecord(value))
+        throw new SchemaError(PROVIDER, 'Ukrposhta returned an invalid tracking response');
+    if (value.code === 'captcha_failed')
+        throw new ChallengeError(PROVIDER, 'Ukrposhta rejected automatic browser verification');
+    return value;
+}
+/** Validate calendar digits without assigning a timezone to the wall clock. */
+export function ukrposhtaWallClock(value) {
+    const raw = value.trim();
+    const format = /^\d{2}\.\d{2}\.\d{4} \d{2}:\d{2}$/.test(raw) ? 'dd.MM.yyyy HH:mm'
+        : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(raw) ? "yyyy-MM-dd'T'HH:mm:ss" : null;
+    if (!format)
+        return null;
+    const date = DateTime.fromFormat(raw, format, { zone: 'UTC' });
+    return date.isValid && date.toFormat(format) === raw ? date.toFormat("yyyy-MM-dd'T'HH:mm:ss") : null;
+}
+export function parseUkrposhtaOverview(payload, requested) {
+    const number = normalizeUkrposhtaNumber(requested);
+    const data = envelope(payload);
+    // The native unknown response has no returned barcode. It cannot prove
+    // absence for this reference, even though the page calls it not found.
+    if (isRecord(data.result) && data.result.message === 'Shipment not found')
+        throw new IndeterminateError(PROVIDER);
+    if (!Array.isArray(data.result))
+        throw new SchemaError(PROVIDER, 'Ukrposhta omitted its parcel overview');
+    if (!data.result.length)
+        throw new IndeterminateError(PROVIDER);
+    if (data.result.length !== 1)
+        throw new IndeterminateError(PROVIDER, 'Ukrposhta returned an ambiguous parcel overview');
+    const row = data.result[0];
+    if (!isRecord(row))
+        throw new SchemaError(PROVIDER, 'Ukrposhta returned an invalid parcel overview');
+    if (text(row.barcode, 'overview identity', true).toUpperCase() !== number)
+        throw new SchemaError(PROVIDER, 'Ukrposhta returned a different parcel identity');
+    if (!Number.isInteger(row.step) || Number(row.step) < 1 || Number(row.step) > MAX_SCANS)
+        throw new IndeterminateError(PROVIDER, 'Ukrposhta returned an unresolved history count');
+    return { number, count: Number(row.step), date: text(row.date, 'overview clock'), code: text(row.event, 'overview event code', true),
+        label: text(row.eventName, 'overview status', true), location: text(row.name, 'overview location'), country: text(row.country, 'overview country') };
+}
+export function parseUkrposhtaHistory(payload, overview) {
+    const data = envelope(payload);
+    if (!isRecord(data.from_to) || !Array.isArray(data.result))
+        throw new SchemaError(PROVIDER, 'Ukrposhta omitted its parcel history');
+    if (![0, false, '0'].includes(data.from_to.ISSEVERALPLACES)
+        || data.several_places === true)
+        throw new IndeterminateError(PROVIDER, 'Ukrposhta returned a shipment with multiple pieces');
+    // This auxiliary flag is false for both positive histories and unknown
+    // references. It is not a barcode-recognition signal.
+    if (data.date_by_barcode != null && typeof data.date_by_barcode !== 'boolean')
+        throw new SchemaError(PROVIDER, 'Ukrposhta returned an invalid auxiliary date flag');
+    if (!data.result.length)
+        throw new IndeterminateError(PROVIDER);
+    if (data.result.length > MAX_SCANS)
+        throw new SchemaError(PROVIDER, 'Ukrposhta returned excessive history');
+    if (data.result.length !== overview.count)
+        throw new IndeterminateError(PROVIDER, 'Ukrposhta returned incomplete or changed history');
+    const checkIdentity = (value) => {
+        if (value != null && text(value, 'history identity', true).toUpperCase() !== overview.number)
+            throw new SchemaError(PROVIDER, 'Ukrposhta returned a different history identity');
+    };
+    checkIdentity(data.nod_barcode);
+    const rows = data.result.map((raw) => {
+        if (!isRecord(raw))
+            throw new SchemaError(PROVIDER, 'Ukrposhta returned an invalid history row');
+        checkIdentity(raw.nod_barcode);
+        return { date: text(raw.gtt_date, 'scan clock'), code: text(raw.gtt_event, 'scan code', true),
+            label: text(raw.gtt_event_name, 'scan status', true), location: text(raw.gtt_name, 'scan location'), country: text(raw.gtt_country, 'scan country'),
+            reason: text(raw.gtt_eventreason_id, 'scan reason code') };
+    });
+    const latest = rows[0];
+    const latestClock = ukrposhtaWallClock(latest.date), overviewClock = ukrposhtaWallClock(overview.date);
+    // The overview carries seconds that the full native history omits. Bind
+    // at the history's minute precision without promoting overview seconds.
+    const sameClock = latestClock !== null && overviewClock !== null
+        ? latestClock.slice(0, 16) === overviewClock.slice(0, 16) : latest.date === overview.date;
+    if (!sameClock || latest.code !== overview.code || latest.label !== overview.label
+        || latest.location !== overview.location || latest.country !== overview.country)
+        throw new IndeterminateError(PROVIDER, 'Ukrposhta overview and current history disagree');
+    // Both native histories are current-first. Keep that order across foreign
+    // wall clocks or missing dates instead of sorting them as UTC instants.
+    let returnLeg = false;
+    const events = Array(rows.length);
+    for (let index = rows.length - 1; index >= 0; index--) {
+        const row = rows[index];
+        if (ukrposhtaReturnCue(row.label))
+            returnLeg = true;
+        let classified = ukrposhtaStatus(row.code);
+        if (row.reason === '65' || row.reason === '66')
+            classified = { status: 'exception', stage: 'exception' };
+        if (classified?.stage === 'delivered' && returnLeg)
+            classified = { status: 'exception', stage: 'returned' };
+        const local = ukrposhtaWallClock(row.date);
+        events[index] = {
+            description: row.label, provider_code: row.code,
+            ...(row.location || row.country ? { location: [row.location, row.country].filter(Boolean).join(', ') } : {}),
+            ...(local ? { local_time: local } : row.date ? { provider_time_text: row.date } : {}),
+            ...(classified ? { stage: classified.stage } : {}), ...(returnLeg ? { provider_leg: 'return' } : {}),
+        };
+    }
+    const current = events[0];
+    const stage = current.stage;
+    const status = stage === 'returned' || stage === 'exception' ? 'exception' : ukrposhtaStatus(latest.code)?.status ?? 'unknown';
+    const seen = new Set();
+    const deduplicated = events.filter(event => { const key = JSON.stringify(event); if (seen.has(key))
+        return false; seen.add(key); return true; });
+    return { status, ...(stage ? { current_stage: stage } : {}), last_status_text: latest.label, last_update: null, events: deduplicated.slice(0, 100) };
+}

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

@@ -0,0 +1,3 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function ukrposhtaStatus(code: string): ClassifiedStatus | undefined;
+export declare function ukrposhtaReturnCue(label: string): boolean;

package/dist/carriers/ukrposhta/status.js

@@ -0,0 +1,34 @@
+const CODES = {
+    '10601': { status: 'pending', stage: 'registered' },
+    '10100': { status: 'in_transit', stage: 'accepted' },
+    '20700': { status: 'in_transit', stage: 'in_transit' },
+    '20800': { status: 'in_transit', stage: 'in_transit' },
+    '21600': { status: 'in_transit', stage: 'in_transit' },
+    '21700': { status: 'in_transit', stage: 'ready_for_pickup' },
+    '2201': { status: 'in_transit', stage: 'in_transit' },
+    '24300': { status: 'in_transit', stage: 'customs' },
+    '27900': { status: 'in_transit', stage: 'in_transit' },
+    '29500': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    '31200': { status: 'exception', stage: 'exception' },
+    '4006': { status: 'in_transit', stage: 'in_transit' },
+    '4021': { status: 'in_transit', stage: 'in_transit' },
+    '4024': { status: 'in_transit', stage: 'in_transit' },
+    '4074': { status: 'in_transit', stage: 'in_transit' },
+    '41000': { status: 'delivered', stage: 'delivered' },
+    '48000': { status: 'delivered', stage: 'delivered' },
+    '67300': { status: 'in_transit', stage: 'in_transit' },
+    '70800': { status: 'in_transit', stage: 'in_transit' },
+    '82700': { status: 'in_transit', stage: 'customs' },
+    '82800': { status: 'in_transit', stage: 'in_transit' },
+    '89000': { status: 'in_transit', stage: 'customs' },
+    '89100': { status: 'in_transit', stage: 'in_transit' },
+    '97700': { status: 'in_transit', stage: 'in_transit' },
+};
+export function ukrposhtaStatus(code) {
+    return Object.hasOwn(CODES, code) ? CODES[code] : undefined;
+}
+// "Returned to Sender" is the decision to start the journey back. The
+// separate "Return: Delivered to Sender" scan confirms its completion.
+export function ukrposhtaReturnCue(label) {
+    return /^Return: /i.test(label) || /^Returned to Sender(?:\s|\()/i.test(label);
+}

package/dist/carriers/ukrposhta/statuses.json

@@ -0,0 +1,208 @@
+{
+  "carrier": "ukrposhta",
+  "entries": [
+    {
+      "code": "41000",
+      "wording": "Return: Delivered to Sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "21700",
+      "wording": "Return: Arrived to the Branch",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20800",
+      "wording": "Return: Departed from the Logistics Center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20700",
+      "wording": "Return: Arrived to the Logistics Center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20800",
+      "wording": "Return: Departed from the Branch",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "31200",
+      "wording": "Returned to Sender (Due to Recipient's Refusal)",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "21700",
+      "wording": "Arrived to the Branch",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20800",
+      "wording": "Departed from the Branch",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "10100",
+      "wording": "Registered",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "10601",
+      "wording": "Created online. Waiting acceptance",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "48000",
+      "wording": "Final delivery",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "29500",
+      "wording": "Item out for physical delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "27900",
+      "wording": "Arrival at the delivery office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "97700",
+      "wording": "Departure from inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "89100",
+      "wording": "Released from customs for further delivery",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "89000",
+      "wording": "Item presented to customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "24300",
+      "wording": "Held at inward office of exchange",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "67300",
+      "wording": "Arrival at inward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "2201",
+      "wording": "Accepted by destination post for processing",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "4021",
+      "wording": "Сonsignment with your postal item has arrived to the airport of destination country",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "4024",
+      "wording": "Consignment with your postal item has been sent from the airport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "4006",
+      "wording": "Consignment with your postal item is being prepared for the flight to be sent from the airport.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "4074",
+      "wording": "Consignment with your postal item has been received by carrier for further transportation",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "70800",
+      "wording": "The postal item has been processed at the office of exchange and handed over for further transportation to the destination country",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "82800",
+      "wording": "Released from customs for further delivery",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "82700",
+      "wording": "Item presented to customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "21600",
+      "wording": "Arrival at outward office of exchange",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20700",
+      "wording": "Arrived to the Logistics Center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "20800",
+      "wording": "Departed from the Logistics Center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class UniuniTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/uniuni/adapter.js

@@ -0,0 +1,48 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { normalizeUniuniNumber, normalizeUniuniRecognitionNumber, parseUniuni } from './parser.js';
+const ENDPOINT = 'https://tracking-service-api.uniuni.ca/tracking/trackinguniuninew';
+// Fixed anonymous website configuration from the official tracking client;
+// this is neither an account credential nor an issued browser/session token.
+const WEB_KEY = 'SMq45nJhQuNR3WHsJA6N'; // gitleaks:allow
+export class UniuniTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeUniuniNumber(raw);
+        return runSteps({ carrier: 'uniuni', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    let bytes;
+                    try {
+                        const params = new URLSearchParams({ id: number, key: WEB_KEY, source: 'web' });
+                        ({ bytes } = await fetchBounded(`${ENDPOINT}?${params}`, { signal, headers: { Accept: 'application/json' } }, {
+                            provider: 'UniUni', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000, fetcher: this.options.fetcher,
+                        }));
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                            throw new TransportError('UniUni', 'UniUni tracking endpoint is unavailable', { cause: error });
+                        }
+                        throw error;
+                    }
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'UniUni');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('UniUni', 'UniUni returned invalid tracking JSON', { cause });
+                    }
+                    return parseUniuni(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new UniuniTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'uniuni', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeUniuniRecognitionNumber(number))) };
+};

package/dist/carriers/uniuni/carrier.json

@@ -0,0 +1,90 @@
+{
+  "id": "uniuni",
+  "displayName": "UniUni",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CA",
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#f68841"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "uniuni",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 33
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.uniuni.com/tracking/?no={trackingNumber}",
+    "canaryUrl": "https://www.uniuni.com/tracking/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "delivered_at",
+      "estimated_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "delivered_at"
+    ],
+    "discarded": [
+      "inactive_legacy_estimates",
+      "detailed_delivery_prose",
+      "addresses",
+      "coordinates",
+      "operators",
+      "proof_images"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "uniuni.com"
+      ],
+      "params": [
+        "no"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "uniuni-1",
+      "pattern": "^UUS[A-Z0-9]{16}$",
+      "confidence": "high"
+    },
+    {
+      "id": "uniuni-2",
+      "pattern": "^4C\\d{9}US$",
+      "confidence": "high"
+    },
+    {
+      "id": "uniuni-3",
+      "pattern": "^UUSC\\d{12}$",
+      "confidence": "high"
+    },
+    {
+      "id": "uniuni-4",
+      "pattern": "^U9999\\d{11}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/uniuni/numbers.json

@@ -0,0 +1,72 @@
+{
+  "carrier": "uniuni",
+  "records": [
+    {
+      "number": "4C003925742US",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.bbb.org/scamtracker/lookupscam/1107364",
+        "date": "2025-11-03"
+      },
+      "expect": {
+        "carrier": "uniuni",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "U999900000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-30",
+      "expect": {
+        "carrier": "uniuni",
+        "confidence": "high"
+      },
+      "note": "Made-up number in the public U9999 layout: U9999 and 11 digits."
+    },
+    {
+      "number": "U999902043194518",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a377f54201c02cc2070d830",
+        "date": "2026-06-21"
+      },
+      "expect": {
+        "carrier": "uniuni",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number with identity-bound history in the official anonymous feed."
+    },
+    {
+      "number": "UUS5B60564241706199",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.bbb.org/scamtracker/lookupscam/1111994"
+      },
+      "expect": {
+        "carrier": "uniuni",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "UUSC000019638703",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a9c981600b86f86c0b46985",
+        "date": "2026-09-06"
+      },
+      "expect": {
+        "carrier": "uniuni",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number with identity-bound history in the official anonymous feed."
+    }
+  ]
+}

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

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeUniuniNumber(raw: string): string;
+/** Discovery only probes formats confirmed for individual parcels. */
+export declare function normalizeUniuniRecognitionNumber(raw: string): string;
+export declare function parseUniuni(payload: unknown, rawNumber: string): CarrierResult;