universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,49 @@
+{
+  "carrier": "nz-post",
+  "records": [
+    {
+      "number": "EP318770974NZ",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "nz-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "LX072774186NZ",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.chinapostaltracking.com/qa/package-stuck-160626/",
+        "date": "2026-08-31"
+      },
+      "expect": {
+        "carrier": "nz-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Sent from New Zealand to China."
+    },
+    {
+      "number": "XY123456789NZ",
+      "role": "negative",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.nzpost.co.nz/business/developer-centre/nz-post-legacy-apis/tracking-api/track-method"
+      },
+      "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 NZ Post, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/nz-post/parser.d.ts

@@ -0,0 +1,3 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeNzPostNumber(raw: string): string;
+export declare function parseNzPost(payload: unknown, number: string): CarrierResult;

package/dist/carriers/nz-post/parser.js

@@ -0,0 +1,97 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyNzPostStatus } from './status.js';
+export function normalizeNzPostNumber(raw) {
+    const number = raw.toUpperCase().replace(/\s/g, '');
+    if (!/^\d{20}$/.test(number) && !isValidS10TrackingNumber(number)) {
+        throw new TypeError('NZ Post requires a domestic parcel barcode or valid postal tracking number');
+    }
+    return number;
+}
+function clock(value) {
+    if (value != null && typeof value !== 'string')
+        throw new SchemaError('nz-post', 'NZ Post returned an invalid clock field');
+    const raw = clean(value, 64);
+    const iso = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/i.test(raw)
+        ? explicitOffsetTime(raw) : null;
+    if (iso)
+        return { time: iso.iso };
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?$/.test(raw)) {
+        const parsed = DateTime.fromISO(raw, { zone: 'UTC' });
+        const local = parsed.isValid ? parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) : null;
+        if (local)
+            return { local_time: local };
+    }
+    return raw ? { provider_time_text: raw } : {};
+}
+export function parseNzPost(payload, number) {
+    const requested = normalizeNzPostNumber(number);
+    if (!isRecord(payload) || typeof payload.success !== 'boolean' || !Number.isInteger(payload.status_code))
+        throw new SchemaError('nz-post');
+    if (payload.success !== true)
+        throw new IndeterminateError('nz-post', 'NZ Post did not complete the lookup');
+    if (!Array.isArray(payload.results) || payload.results.length > 100 || !payload.results.every(isRecord))
+        throw new SchemaError('nz-post');
+    if (!payload.results.length)
+        throw new IndeterminateError('nz-post', 'NZ Post returned no parcel result');
+    if (payload.results.length !== 1 || typeof payload.results[0].tracking_reference !== 'string'
+        || payload.results[0].tracking_reference.trim().toUpperCase() !== requested) {
+        throw new SchemaError('nz-post', 'NZ Post did not return one exact parcel reference');
+    }
+    const item = payload.results[0];
+    if (item.errors !== undefined) {
+        if (!Array.isArray(item.errors) || !item.errors.every(isRecord))
+            throw new SchemaError('nz-post');
+        if (item.errors.length) {
+            const error = item.errors[0];
+            if (payload.status_code === 2 && item.errors.length === 1 && !Object.hasOwn(item, 'tracking_events')
+                && error.code === 400002 && error.message === 'Invalid parameter(s)'
+                && error.details === 'No data found for this Tracking Reference')
+                throw new NotFoundError('nz-post');
+            throw new IndeterminateError('nz-post', 'NZ Post returned an unrecognized tracking error');
+        }
+    }
+    if (payload.status_code !== 1)
+        throw new IndeterminateError('nz-post', 'NZ Post returned an incomplete lookup');
+    if (!Array.isArray(item.tracking_events) || item.tracking_events.length > 500)
+        throw new SchemaError('nz-post');
+    const projected = item.tracking_events.map((raw) => {
+        if (!isRecord(raw))
+            throw new SchemaError('nz-post');
+        const description = clean(raw.status, 300);
+        const code = clean(raw.edifact_code, 40);
+        if (!description || !code)
+            throw new SchemaError('nz-post', 'NZ Post returned an incomplete scan');
+        const location = clean(raw.depot_name, 160);
+        const mapped = classifyNzPostStatus(code);
+        // Long descriptions embed signatures and other recipient details. The
+        // short status and depot name carry the tracking evidence independently.
+        return { ...clock(raw.date_time), description, provider_code: code,
+            ...(location ? { location } : {}), ...(mapped ? { stage: mapped.stage } : {}) };
+    });
+    if (!projected.length)
+        throw new IndeterminateError('nz-post', 'NZ Post returned no parcel history');
+    // The consumer client treats the last source row as current. Preserve that
+    // order if any clock is unresolved instead of promoting an older dated row.
+    projected.reverse();
+    if (projected.every(event => event.time))
+        projected.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const seen = new Set();
+    const events = projected.filter(event => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const latest = events[0];
+    const current = classifyNzPostStatus(latest.provider_code);
+    return { status: current?.status ?? 'unknown', ...(current ? { current_stage: current.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null,
+        ...(latest.local_time ? { last_update_local: latest.local_time } : {}), expected_delivery: null,
+        ...(current?.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}), events: events.slice(0, 100) };
+}

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

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

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

@@ -0,0 +1,29 @@
+// EDIFACT groups used by the official consumer tracking client. Pickup requests
+// are pre-advice; they do not establish that NZ Post has collected the parcel.
+const CODES = {
+    '997': { status: 'pending', stage: 'registered' },
+    '205': { status: 'pending', stage: 'registered' },
+    '206': { status: 'pending', stage: 'registered' },
+    '13': { status: 'in_transit', stage: 'accepted' },
+    '8': { status: 'in_transit', stage: 'in_transit' },
+    '58': { status: 'in_transit', stage: 'in_transit' },
+    '40': { status: 'exception', stage: 'exception' },
+};
+const DELIVERED = new Set(['22', '5022', '6033', '5207', '4014']);
+const DELIVERY = new Set(['5322', '32', '35', '5045', '5323', '6032', '6035']);
+const ATTEMPTED = new Set(['42', '50', '51', '52', '53', '62', '63', '5021', '5312', '5313',
+    '5314', '5315', '5316', '5317', '5318', '5319', '5320', '4003', '6019', '6048']);
+const COLLECTION = new Set(['141', '6003', '5351', '99', '1099', '2099']);
+export function classifyNzPostStatus(code) {
+    if (Object.hasOwn(CODES, code))
+        return CODES[code];
+    if (DELIVERED.has(code))
+        return { status: 'delivered', stage: 'delivered' };
+    if (DELIVERY.has(code))
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    if (ATTEMPTED.has(code))
+        return { status: 'exception', stage: 'exception' };
+    if (COLLECTION.has(code))
+        return { status: 'in_transit', stage: 'ready_for_pickup' };
+    return undefined;
+}

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

@@ -0,0 +1,68 @@
+{
+  "carrier": "nz-post",
+  "entries": [
+    {
+      "code": "997",
+      "wording": "Tracking number allocated to parcel",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "13",
+      "wording": "Collected from sender",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "8",
+      "wording": "Processed at depot",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "32",
+      "wording": "With courier for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "22",
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "205",
+      "wording": "Parcel pickup request received",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "206",
+      "wording": "Parcel pickup request allocated to driver",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "40",
+      "wording": "Delayed",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "58",
+      "wording": "Ready for courier",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/old-dominion/carrier.json

@@ -0,0 +1,51 @@
+{
+  "id": "old-dominion",
+  "displayName": "Old Dominion",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#00693e"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.odfl.com/us/en/tools/trace-track-ltl-freight/trace.html?proNumbers={trackingNumber}",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "odfl.com"
+      ],
+      "params": [
+        "proNumbers"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "old-dominion-1",
+      "pattern": "^(?:072|777|778|780)\\d{8}$",
+      "confidence": "high"
+    },
+    {
+      "id": "old-dominion-2",
+      "pattern": "^80\\d{9}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/old-dominion/numbers.json

@@ -0,0 +1,83 @@
+{
+  "carrier": "old-dominion",
+  "records": [
+    {
+      "number": "07209562763",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "77767553207",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "77806528897",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "78045768393",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "80003280379",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "80993847369",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/old_dominion.json"
+      },
+      "expect": {
+        "carrier": "old-dominion",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class OntracTracker {
+    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/ontrac/adapter.js

@@ -0,0 +1,34 @@
+import { IndeterminateError } 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 { normalizeOntracNumber, parseOntrac } from './parser.js';
+// Endpoint and schema come from the current official portal client:
+// https://www.ontrac.com/wp-content/themes/ontrac/assets/js/ontrac-package-status.js
+const ENDPOINT = 'https://webtrack.ontrac.com/PackageServices/tracking/';
+export class OntracTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeOntracNumber(raw);
+        return runSteps({ carrier: 'ontrac', budgetMs: context.budgetMs ?? 15_000,
+            signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const { response, bytes } = await fetchBounded(`${ENDPOINT}${encodeURIComponent(number)}`, {
+                        headers: { Accept: 'application/json' }, signal,
+                    }, { provider: 'OnTrac', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
+                        allowHttpStatuses: [404, 410], fetcher: this.options.fetcher });
+                    if (response.status === 404 || response.status === 410) {
+                        // The portal returns generic ProblemDetails for unknown numbers; the
+                        // same envelope can mean a missing API route rather than no parcel.
+                        throw new IndeterminateError('OnTrac', 'OnTrac could not return the tracking resource');
+                    }
+                    return parseOntrac(parseJsonBytes(bytes, 'OnTrac'), number);
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new OntracTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'ontrac', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/ontrac/carrier.json

@@ -0,0 +1,81 @@
+{
+  "id": "ontrac",
+  "displayName": "OnTrac",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#cc2027"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ontrac",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "estimated_delivery",
+    "weight"
+  ],
+  "portal": {
+    "url": "https://www.ontrac.com/tracking/?number={trackingNumber}",
+    "canaryUrl": "https://www.ontrac.com/tracking/",
+    "shows": [
+      "status",
+      "history",
+      "estimated_delivery",
+      "weight"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "estimated_delivery",
+      "weight"
+    ],
+    "discarded": [
+      "recipient",
+      "signature"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "ontrac.com"
+      ],
+      "params": [
+        "number"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "ontrac-1",
+      "pattern": "^[CD]\\d{14}$",
+      "confidence": "high"
+    },
+    {
+      "id": "ontrac-2",
+      "pattern": "^L[AIEHNX]\\d{8}$",
+      "confidence": "high"
+    },
+    {
+      "id": "ontrac-3",
+      "pattern": "^1LS\\d{12,14}$",
+      "confidence": "high"
+    },
+    {
+      "id": "ontrac-4",
+      "pattern": "^1LS[A-Z0-9]{12,14}$",
+      "confidence": "high"
+    }
+  ]
+}