universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,67 @@
+/** The official client's package enum and English translations. */
+export const CANADA_POST_STATUS_STAGE = {
+    HalfAccepted: 'registered', FullAccepted: 'accepted', InTransit: 'in_transit',
+    InTransitAlert: 'exception', FullProgressAlert: 'exception', FullProgress: 'out_for_delivery',
+    HalfDelivered: 'failed_attempt', ReadyPickup: 'ready_for_pickup', Delivered: 'delivered',
+    '0': 'registered', '1': 'accepted', '2': 'in_transit', '3': 'exception', '4': 'exception',
+    '5': 'out_for_delivery', '6': 'failed_attempt', '7': 'ready_for_pickup', '8': 'delivered',
+};
+export function canadaPostPackageStage(code) {
+    return Object.hasOwn(CANADA_POST_STATUS_STAGE, code) ? CANADA_POST_STATUS_STAGE[code] : null;
+}
+const SCAN_STAGE = {
+    '2600': 'in_transit', '1481': 'exception', '0156': 'ready_for_pickup', '0172': 'exception',
+    '1701': 'ready_for_pickup', '1703': 'in_transit', '0174': 'out_for_delivery', '0170': 'in_transit',
+    '1301': 'accepted', '1466': 'delivered', '0500': 'out_for_delivery', '2407': 'ready_for_pickup',
+    '0405': 'accepted', '0175': 'in_transit', '0100': 'in_transit', '1302': 'accepted',
+};
+export function canadaPostScanStage(code) {
+    return Object.hasOwn(SCAN_STAGE, code) ? SCAN_STAGE[code] : null;
+}
+export function canadaPostStage(text) {
+    const value = text.toLowerCase();
+    if (/\b(?:will|may|might|would)\b.*\breturn(?:ed)?\b/.test(value))
+        return /notice|pick[ -]?up|collect/.test(value) ? 'ready_for_pickup' : null;
+    if (/\b(?:en\s?route|in transit)\b.*\bsender\b/.test(value))
+        return 'in_transit';
+    if (/\breturned to (?:the )?sender\b/.test(value))
+        return 'returned';
+    if (/\b(?:being returned|returning|return to sender)\b/.test(value))
+        return 'exception';
+    if (/available for pick[ -]?up|held at (?:the )?post office/.test(value))
+        return 'ready_for_pickup';
+    if (/delivery attempt|notice left|delivery notice|no answer|business closed|not delivered|unable to deliver|recipient not located/.test(value))
+        return 'failed_attempt';
+    if (/\b(?:will|expected|scheduled)\b.*\bdelivered\b/.test(value))
+        return null;
+    if (/\bdelivered\b/.test(value))
+        return 'delivered';
+    if (/out for delivery/.test(value))
+        return 'out_for_delivery';
+    if (/customs|clearance/.test(value))
+        return 'customs';
+    if (/exception|alert|delay|damaged|lost|seized|held|re-routed due to processing error/.test(value))
+        return 'exception';
+    if (/manifest|label created|information (?:received|submitted)|order received|pre-shipment|waiting for item/.test(value))
+        return 'registered';
+    if (/accepted|picked up|received by canada post|item arrived|arrived at/.test(value))
+        return 'accepted';
+    if (/in transit|on its way|departed|processed|processing|distribution cent(?:re|er)|sorting/.test(value))
+        return 'in_transit';
+    return null;
+}
+export function statusForStage(stage) {
+    if (stage === 'delivered')
+        return 'delivered';
+    if (stage === 'out_for_delivery' || stage === 'ready_for_pickup')
+        return 'out_for_delivery';
+    if (stage === 'exception' || stage === 'failed_attempt' || stage === 'returned')
+        return 'exception';
+    if (stage === 'registered' || stage === 'pending')
+        return 'pending';
+    return 'in_transit';
+}
+export function canadaPostStatus(code, text) {
+    const stage = canadaPostPackageStage(code.trim()) ?? canadaPostStage(text);
+    return stage ? statusForStage(stage) : 'unknown';
+}

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

@@ -0,0 +1,171 @@
+{
+  "carrier": "canada-post",
+  "entries": [
+    {
+      "code": "HalfAccepted",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "FullAccepted",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "InTransit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "InTransitAlert",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "FullProgressAlert",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "FullProgress",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "HalfDelivered",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "ReadyPickup",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "bundle"
+    },
+    {
+      "code": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "2600",
+      "wording": "Item has been returned and is enroute to the Sender",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1481",
+      "wording": "Recipient not located at address provided. Item being returned to sender.",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0156",
+      "wording": "Final Notice; Item will be returned to sender if not collected within 10 days",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0172",
+      "wording": "Item re-routed due to processing error; Possible delay",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1701",
+      "wording": "Item available for pickup at Post Office",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1703",
+      "wording": "Item in transit to Post Office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0174",
+      "wording": "Item out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0170",
+      "wording": "Item processed",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1301",
+      "wording": "Item accepted at the Post Office",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1466",
+      "wording": "Delivered to mailroom",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0500",
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "2407",
+      "wording": "Item available for pick-up",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0405",
+      "wording": "Item arrived",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0175",
+      "wording": "Item in transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "0100",
+      "wording": "Item processed",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "1302",
+      "wording": "Item accepted at the Post Office",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/canpar/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 CanparTracker {
+    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/canpar/adapter.js

@@ -0,0 +1,40 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { SchemaError, TransportError } 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 { normalizeCanparNumber, parseCanpar } from './parser.js';
+const ENDPOINT = 'https://canship.canpar.com/api/CanparAddons/trackByBarcodeV2';
+export class CanparTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeCanparNumber(raw);
+        return runSteps({ carrier: 'canpar', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    signal.throwIfAborted();
+                    const { response, bytes } = await fetchBounded(ENDPOINT, { method: 'POST', signal,
+                        headers: { Accept: 'application/json', 'Content-Type': 'application/json; charset=utf-8' },
+                        body: JSON.stringify({ barcode: number, track_shipment: false }),
+                    }, { provider: 'Canpar', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
+                        allowHttpStatuses: [404, 410], fetcher: this.options.fetcher });
+                    if (response.status !== 200)
+                        throw new TransportError('Canpar', 'Canpar tracking endpoint is unavailable');
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'Canpar');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('Canpar', 'Canpar returned invalid tracking JSON', { cause });
+                    }
+                    return parseCanpar(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new CanparTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'canpar', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCanparNumber(number))) };
+};

package/dist/carriers/canpar/carrier.json

@@ -0,0 +1,74 @@
+{
+  "id": "canpar",
+  "displayName": "Canpar",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CA"
+    ]
+  },
+  "brand": {
+    "color": "#003b70"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "canpar",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 34
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://www.canpar.com/en/tracking/track.htm?barcode={trackingNumber}",
+    "canaryUrl": "https://www.canpar.com/en/tracking/track.htm",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "estimated_delivery",
+      "proof_of_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "estimated_delivery",
+      "proof_of_delivery",
+      "recipient",
+      "addresses",
+      "comments",
+      "contacts",
+      "references"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "canpar.com"
+      ],
+      "params": [
+        "barcode",
+        "reference"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "canpar-1",
+      "pattern": "^[CDKLSUXZ]\\d{21}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/canpar/numbers.json

@@ -0,0 +1,71 @@
+{
+  "carrier": "canpar",
+  "records": [
+    {
+      "number": "D434031340000025200001",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/69f1217925267d3e588981cf",
+        "date": "2026-04-28"
+      },
+      "expect": {
+        "carrier": "canpar",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "D576002440000001428004",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canpar.json"
+      },
+      "expect": {
+        "carrier": "canpar",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "D576002440000001718010",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canpar.json"
+      },
+      "expect": {
+        "carrier": "canpar",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "L576002440000000001004",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canpar.json"
+      },
+      "expect": {
+        "carrier": "canpar",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "S576002440000000004001",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canpar.json"
+      },
+      "expect": {
+        "carrier": "canpar",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

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

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

package/dist/carriers/canpar/parser.js

@@ -0,0 +1,75 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { canparStatus } from './status.js';
+export function normalizeCanparNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^[CDKLSUXZ]\d{21}$/.test(number))
+        throw new TypeError('Canpar requires a full parcel barcode');
+    return number;
+}
+function clock(raw) {
+    if (raw != null && typeof raw !== 'string')
+        throw new SchemaError('Canpar', 'Canpar returned an invalid scan clock field');
+    const text = clean(raw, 64);
+    const parsed = /^\d{8} (?:[01]\d|2[0-3])[0-5]\d[0-5]\d$/.test(text)
+        ? DateTime.fromFormat(text, 'yyyyMMdd HHmmss', { zone: 'UTC' }) : null;
+    // The public client displays these digits as local clocks and ignores
+    // time_shift. That field does not consistently describe a UTC offset.
+    return parsed?.isValid ? { local_time: parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) }
+        : text ? { provider_time_text: text } : {};
+}
+export function parseCanpar(payload, rawNumber) {
+    const number = normalizeCanparNumber(rawNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('Canpar');
+    if (payload.error != null)
+        throw new IndeterminateError('Canpar', 'Canpar returned an inconclusive tracking response');
+    const packages = Array.isArray(payload.result) ? payload.result
+        : isRecord(payload.result) ? payload.result.packages : null;
+    if (!Array.isArray(packages) || packages.length > 25 || !packages.every(isRecord))
+        throw new SchemaError('Canpar');
+    if (!packages.length)
+        throw new IndeterminateError('Canpar', 'Canpar returned no parcel history');
+    if (packages.length !== 1 || packages[0].barcode !== number) {
+        throw new SchemaError('Canpar', 'Canpar did not identify one matching parcel');
+    }
+    const item = packages[0];
+    if (!Array.isArray(item.events) || item.events.length > 500)
+        throw new SchemaError('Canpar');
+    // Unknown barcodes can return an identity-shaped empty package. Its status
+    // and delivered flag establish neither a registered parcel nor absence.
+    if (!item.events.length)
+        throw new IndeterminateError('Canpar', 'Canpar returned no parcel history');
+    const events = [];
+    const seen = new Set();
+    // The official widget displays this newest-first sequence without sorting.
+    // Preserve equal-clock positions and cross-region local clocks.
+    for (const row of item.events) {
+        if (!isRecord(row))
+            throw new SchemaError('Canpar', 'Canpar returned an incomplete scan');
+        const code = clean(row.code, 16);
+        const description = clean(row.code_description_en, 500);
+        if (!code || !description)
+            throw new SchemaError('Canpar', 'Canpar returned a scan without status or wording');
+        const mapped = canparStatus(code);
+        const address = isRecord(row.address) ? row.address : null;
+        const location = address ? [clean(address.city, 100), clean(address.province, 20)].filter(Boolean).join(', ') : '';
+        const event = { description, provider_code: code, ...clock(row.local_date_time),
+            ...(location ? { location } : {}), ...(mapped ? { stage: mapped.stage } : {}) };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(event);
+        }
+    }
+    const latest = events[0];
+    const mapped = canparStatus(latest.provider_code);
+    // RTN describes a completed return scan, not an instruction to relabel
+    // every later scan. Native histories can resume movement and delivery.
+    return { status: mapped?.status ?? 'unknown', ...(mapped ? { current_stage: mapped.stage } : {}),
+        last_status_text: latest.description, last_update: null, last_update_local: latest.local_time ?? null,
+        expected_delivery: null, events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/canpar/status.js

@@ -0,0 +1,16 @@
+const codes = {
+    DEL: { status: 'delivered', stage: 'delivered' },
+    NSR: { status: 'delivered', stage: 'delivered' },
+    WC: { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    PIC: { status: 'in_transit', stage: 'accepted' },
+    ARR: { status: 'in_transit', stage: 'in_transit' },
+    DPT: { status: 'in_transit', stage: 'in_transit' },
+    SRT: { status: 'in_transit', stage: 'in_transit' },
+    COA: { status: 'in_transit', stage: 'in_transit' },
+    MIS: { status: 'exception', stage: 'exception' },
+    NL: { status: 'exception', stage: 'failed_attempt' },
+    RTN: { status: 'exception', stage: 'returned' },
+};
+export function canparStatus(code) {
+    return Object.hasOwn(codes, code) ? codes[code] : undefined;
+}

package/dist/carriers/canpar/statuses.json

@@ -0,0 +1,82 @@
+{
+  "carrier": "canpar",
+  "entries": [
+    {
+      "code": "DEL",
+      "wording": "Our Package was Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "SRT",
+      "wording": "Sorting It Out-Stay Tuned!",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "MIS",
+      "wording": "Package was sorted to the incorrect terminal",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "ARR",
+      "wording": "Package Has Arrived at Our Facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RTN",
+      "wording": "Returned to Sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "DPT",
+      "wording": "Departing sort facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "PIC",
+      "wording": "Picked Up and On the Move!",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "NSR",
+      "wording": "Your Package was Delivered with no Signature Required",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "WC",
+      "wording": "Out for Delivery-Almost There!",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "COA",
+      "wording": "Change of Address",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "NL",
+      "wording": "Can't Find the Address-Checking Again!",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/china-post/carrier.json

@@ -0,0 +1,38 @@
+{
+  "id": "china-post",
+  "displayName": "China Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#006d46"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.ems.com.cn/mailtracking/you_jian_cha_xun.html",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "china-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}CN$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}