universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/purolator/numbers.json

@@ -0,0 +1,146 @@
+{
+  "carrier": "purolator",
+  "records": [
+    {
+      "number": "287809468872",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Purolator, which stays one candidate among several."
+    },
+    {
+      "number": "320595463938",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Purolator, which stays one candidate among several."
+    },
+    {
+      "number": "331426749957",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Purolator, which stays one candidate among several."
+    },
+    {
+      "number": "CGK002986959",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "purolator",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "EWN001815469",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aa47d13e59cb2883d7ebb28",
+        "date": "2026-09-12"
+      },
+      "expect": {
+        "carrier": "purolator",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "JFV247545960",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "purolator",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "KYV009956937",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "purolator",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "TLR000083964",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/purolator.json"
+      },
+      "expect": {
+        "carrier": "purolator",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

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

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

package/dist/carriers/purolator/parser.js

@@ -0,0 +1,79 @@
+import { DateTime } from 'luxon';
+import { IndeterminateError, 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 { classifyPurolatorStatus } from './status.js';
+export function normalizePurolatorNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^(?:[0-5]\d{11}|(?!BYS)[A-Z]{3}\d{9})$/.test(number))
+        throw new TypeError('Purolator requires a Purolator tracking PIN');
+    return number;
+}
+export function parsePurolator(payload, number) {
+    const requested = normalizePurolatorNumber(number);
+    if (!isRecord(payload) || !Array.isArray(payload.searchResult) || payload.searchResult.length !== 1 || !isRecord(payload.searchResult[0])
+        || !Array.isArray(payload.shipment) || payload.shipment.length > 100)
+        throw new SchemaError('Purolator');
+    const search = payload.searchResult[0];
+    if (search.trackingId !== requested || search.sequenceId !== 1)
+        throw new SchemaError('Purolator', 'Purolator returned a different search');
+    // CONFLICT also occurs for an unknown-looking PIN. It is never a clean negative.
+    if (search.status !== 'FOUND')
+        throw new IndeterminateError('Purolator', 'Purolator did not return a unique matching shipment');
+    if (search.type !== 'PIN' || !Number.isInteger(search.shipmentIndex) || !Number.isInteger(search.packageIndex)
+        || search.shipmentIndex < 0 || search.packageIndex < 0)
+        throw new SchemaError('Purolator');
+    const shipment = payload.shipment[search.shipmentIndex];
+    if (!isRecord(shipment) || !Array.isArray(shipment.package) || shipment.package.length > 100 || !shipment.package.every(isRecord))
+        throw new SchemaError('Purolator');
+    const item = shipment.package[search.packageIndex];
+    if (!item || item.pin !== requested || shipment.package.filter((candidate) => candidate.pin === requested).length !== 1) {
+        throw new SchemaError('Purolator', 'Purolator did not return one matching package');
+    }
+    if (!Array.isArray(item.events) || item.events.length > 500)
+        throw new SchemaError('Purolator');
+    const events = [];
+    const seen = new Set();
+    for (const raw of item.events) {
+        if (!isRecord(raw))
+            throw new SchemaError('Purolator', 'Purolator returned an incomplete scan row');
+        const description = clean(raw.description, 500);
+        const code = clean(raw.code, 64);
+        if (!description || !code)
+            throw new SchemaError('Purolator', 'Purolator returned a scan without wording or code');
+        const rawTime = clean(raw.dateTime, 64);
+        const instant = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/.test(rawTime)
+            ? explicitOffsetTime(rawTime) : null;
+        // The cross-country endpoint sends local wall clocks with no zone. UTC
+        // validates the digits only; it is not assigned to the event.
+        const wall = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(rawTime)
+            ? DateTime.fromFormat(rawTime, 'yyyy-MM-dd HH:mm:ss', { zone: 'UTC' }) : null;
+        const local = wall?.isValid ? wall.toISO({ includeOffset: false, suppressMilliseconds: true }) : null;
+        const location = isRecord(raw.location) ? [clean(raw.location.city, 100), clean(raw.location.provinceState, 32), clean(raw.location.countryCode, 2)].filter(Boolean).join(', ') : '';
+        const key = `${instant?.iso ?? local ?? rawTime}\u0000${code}\u0000${description}\u0000${location}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const mapped = classifyPurolatorStatus(code);
+        events.push({ description, provider_code: code, ...(location ? { location } : {}),
+            ...(instant ? { time: instant.iso } : local ? { local_time: local } : rawTime ? { provider_time_text: rawTime } : {}),
+            ...(mapped ? { stage: mapped.stage } : {}) });
+    }
+    if (!events.length)
+        throw new IndeterminateError('Purolator', 'Purolator returned no tracking scans');
+    // Request eventSortOrder=d and preserve that order, including unresolved clocks.
+    const latest = events[0];
+    const mapped = classifyPurolatorStatus(latest.provider_code ?? '');
+    // Shipment weight describes the entire shipment; do not attach it to one
+    // piece of a multi-package shipment.
+    const measured = shipment.pieceTotalCount === 1 && shipment.package.length === 1 && isRecord(shipment.details) && isRecord(shipment.details.weight)
+        ? shipment.details.weight : null;
+    const weight = measured && typeof measured.value === 'number' && Number.isFinite(measured.value) && measured.value > 0 ? measured.value : null;
+    const unit = measured ? clean(measured.unit, 8).toUpperCase() : '';
+    const weightKg = weight !== null ? unit === 'LB' ? weight * 0.45359237 : unit === 'KG' ? weight : null : null;
+    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?.status === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        ...(weightKg !== null ? { weight_kg: weightKg } : {}), events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/purolator/status.js

@@ -0,0 +1,17 @@
+// Event codes observed in the official anonymous tracking service. The
+// website's lifecycle rail combines these into much broader presentation states.
+const codes = {
+    '3010': { status: 'pending', stage: 'registered' },
+    '2380': { status: 'in_transit', stage: 'accepted' },
+    '0300': { status: 'in_transit', stage: 'in_transit' },
+    '4060': { status: 'in_transit', stage: 'in_transit' },
+    '7220': { status: 'in_transit', stage: 'in_transit' },
+    '7525': { status: 'in_transit', stage: 'in_transit' },
+    '4200': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    '9260': { status: 'exception', stage: 'failed_attempt' },
+    '9550': { status: 'in_transit', stage: 'ready_for_pickup' },
+    '9500': { status: 'delivered', stage: 'delivered' },
+};
+export function classifyPurolatorStatus(code) {
+    return Object.hasOwn(codes, code) ? codes[code] : undefined;
+}

package/dist/carriers/purolator/statuses.json

@@ -0,0 +1,15 @@
+{
+  "carrier": "purolator",
+  "entries": [
+    { "code": "3010", "wording": "Label information electronically submitted", "language": "en", "stage": "registered", "confirmedBy": "live" },
+    { "code": "2380", "wording": "Picked up by Purolator", "language": "en", "stage": "accepted", "confirmedBy": "live" },
+    { "code": "0300", "wording": "Arrived at sort facility", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "4060", "wording": "Arrived at sort facility", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "7220", "wording": "Arrived at sort facility", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "7525", "wording": "Departed sort facility", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "4200", "wording": "On vehicle for delivery", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live" },
+    { "code": "9260", "wording": "Attempted delivery - receiver unavailable", "language": "en", "stage": "failed_attempt", "confirmedBy": "live" },
+    { "code": "9550", "wording": "Available for pickup for 5 business days from arrival date at the counter", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live" },
+    { "code": "9500", "wording": "Shipment delivered", "language": "en", "stage": "delivered", "confirmedBy": "live" }
+  ]
+}

package/dist/carriers/quickpac/carrier.json

@@ -0,0 +1,68 @@
+{
+  "id": "quickpac",
+  "displayName": "Quickpac",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CH"
+    ]
+  },
+  "brand": {
+    "color": "#ed1c24"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "planzer",
+    "upstreamName": "Planzer",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://tracking.app.planzer.ch/delivery/info?deliveryNumber={trackingNumber}",
+    "canaryUrl": "https://tracking.app.planzer.ch/",
+    "shows": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "quickpac.ch"
+      ],
+      "params": [
+        "parcel"
+      ]
+    },
+    {
+      "domains": [
+        "tracking.app.planzer.ch"
+      ],
+      "params": [
+        "deliveryNumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "quickpac-1",
+      "pattern": "^44\\d{16}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/quickpac/numbers.json

@@ -0,0 +1,31 @@
+{
+  "carrier": "quickpac",
+  "records": [
+    {
+      "number": "440010970004135028",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://blog.emeidi.com/2025/05/26/quickpac-pakete-tracken/",
+        "date": "2025-05-26"
+      },
+      "expect": {
+        "carrier": "quickpac",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "440012345612345678",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-10",
+      "expect": {
+        "carrier": "quickpac",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    }
+  ]
+}

package/dist/carriers/quickpac/statuses.json

@@ -0,0 +1,213 @@
+{
+  "carrier": "quickpac",
+  "entries": [
+    {
+      "wording": "Recorded",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "Transferred",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "In delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": ""
+    },
+    {
+      "wording": "Shipped",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-06",
+      "note": "Planzer's English label for delivered (Zugestellt / Livré), never dispatched; stored and shown as \"Delivered\"."
+    },
+    {
+      "wording": "Shipment on the way",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Shipment out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Shipment delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "Not delivered",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "wording": "enregistré",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "erfasst",
+      "language": "de",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "registrato",
+      "language": "it",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "transféré",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "weitergeleitet",
+      "language": "de",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "inoltrato",
+      "language": "it",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "en cours de livraison",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "in zustellung",
+      "language": "de",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "in consegna",
+      "language": "it",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "livré",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "zugestellt",
+      "language": "de",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "consegnato",
+      "language": "it",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Generated localization alias, not an observed API label; an observed label that contradicts it wins."
+    },
+    {
+      "wording": "Erfasst",
+      "language": "de",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"recorded\", \"enregistr\" and \"registrat\"."
+    },
+    {
+      "wording": "Abholung",
+      "language": "de",
+      "stage": "accepted",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"collection\", \"collecte\" and \"ritiro\"."
+    },
+    {
+      "wording": "Umschlaglager",
+      "language": "de",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"transfer depot\", \"transshipment\", \"plateforme\" and \"trasbordo\"."
+    },
+    {
+      "wording": "In Auslieferung",
+      "language": "de",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"out for delivery\", \"en livraison\" and \"in consegna\"."
+    },
+    {
+      "wording": "Ausgeliefert",
+      "language": "de",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Shared capability page route step, matched by substring; also recognizes \"delivered\", \"livré\", \"livrée\" and \"consegnat\"."
+    }
+  ]
+}

package/dist/carriers/relais-colis/adapter.d.ts

@@ -0,0 +1,28 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { NotFoundError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+/**
+ * Kept so the grouped live canary and existing host callers can still match
+ * this name; the taxonomy kind is `not_found` like any other missing shipment.
+ */
+export declare class RelaisColisTrackingError extends NotFoundError {
+    constructor();
+}
+export declare function normalizeRelaisColisTrackingNumber(raw: string): string;
+export declare function relaisColisTrackingUrl(): string;
+export declare function parseRelaisColisTrackingHtml(html: string, rawTrackingNumber: string): CarrierResult;
+export interface RelaisColisTrackerOptions {
+    timeoutMs?: number;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class RelaisColisTracker {
+    readonly timeoutMs: number;
+    readonly fetcher?: typeof fetch;
+    readonly recorder: StepRecorder;
+    constructor(options?: RelaisColisTrackerOptions);
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;