universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/packeta/adapter.js

@@ -0,0 +1,166 @@
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyPacketaStatus, packetaEventStage } from './status.js';
+// Protocol provenance:
+// - Prior art (structure + contract, verified independently below, MIT):
+//   https://github.com/ha-parcel-integrations/ha-packeta (api.py, parcels.py,
+//   tests/payloads.py — keyless consumer POST, 200 {item} / 404 notFound).
+// - Live verification 2026-09-10: POST
+//   https://tracking.packeta.com/api/getPacketById/Z0000000000/en returns
+//   HTTP 404 {"error":"notFound"} in ~0.2s with no cookies, headers or account.
+//   Expired 2023-era reported Z codes return the same 404 (unknown and expired
+//   are intentionally indistinguishable to anonymous callers).
+// - Shape reference: the prior-art payload samples (confirmed live 2026-08-19
+//   against real delivered parcels; values fictionalized there). Only
+//   packetStatusId "3" (delivered) is live-confirmed; the other codes are
+//   reconstructed — an unmapped code is schema drift, never a guess. The maps
+//   live in status.ts.
+const TRACKING_ENDPOINT = 'https://tracking.packeta.com/api/getPacketById';
+const TRACKING_LOCALE = 'en';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_RETURN = 20;
+function parsedTime(value) {
+    const raw = clean(value, 32);
+    if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(raw))
+        return null;
+    // Packeta emits naive wall-clock times with no offset. The backend stamps
+    // Europe/Prague time (verified against real parcels by the prior-art client);
+    // Romania (EET) depot scans can therefore be off by one hour. There is no
+    // per-event locality to do better, so ordering within a parcel is preserved
+    // while the zone caveat stays documented here instead of inventing UTC.
+    return zonedTime(raw, 'yyyy-MM-dd HH:mm:ss', 'Europe/Prague');
+}
+export function normalizePacketaTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^Z\d{10}$/.test(value)) {
+        throw new TypeError('Packeta tracking requires a Z-prefixed barcode with ten digits');
+    }
+    return value;
+}
+export function packetaTrackingUrl(rawTrackingNumber) {
+    // Canonical path form: the legacy ?id= form 301-redirects here (verified live).
+    return `https://tracking.packeta.com/en/${encodeURIComponent(normalizePacketaTrackingNumber(rawTrackingNumber))}`;
+}
+export function parsePacketaTrackingResponse(payload, trackingNumber) {
+    const requested = normalizePacketaTrackingNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('Packeta', 'Packeta returned an invalid tracking response');
+    const item = payload.item;
+    // A 200 carrying an error instead of an item is Packeta's second unknown-code
+    // signal (mirrors the HTTP 404 contract); it is a domain outcome, not a crash.
+    if (!isRecord(item)) {
+        if (typeof payload.error === 'string')
+            throw new NotFoundError('Packeta');
+        throw new SchemaError('Packeta', 'Packeta returned an invalid tracking response');
+    }
+    const returned = clean(item.barcode, 64).toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!returned)
+        throw new SchemaError('Packeta', 'Packeta did not return a shipment identifier');
+    if (returned !== requested)
+        throw new SchemaError('Packeta', 'Packeta returned a different shipment');
+    const code = clean(item.packetStatusId, 16);
+    const classified = classifyPacketaStatus(code);
+    const rawDetails = item.trackingDetails;
+    if (rawDetails !== undefined && !Array.isArray(rawDetails)) {
+        throw new SchemaError('Packeta', 'Packeta returned invalid tracking history');
+    }
+    const parsed = [];
+    const seen = new Set();
+    (Array.isArray(rawDetails) ? rawDetails : []).filter(isRecord).slice(0, 500).forEach((rawEvent, index) => {
+        const time = parsedTime(rawEvent.time);
+        const description = clean(rawEvent.text, 500);
+        if (!time || !description)
+            return;
+        const identity = `${time.iso}\u0000${description}`;
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const stage = packetaEventStage(description);
+        parsed.push({
+            // Unrecognized sentences keep no stage so schema drift surfaces as a
+            // data outcome instead of a wrong movement claim.
+            event: { time: time.iso, location: '', description, ...(stage ? { stage } : {}) },
+            timestamp: time.timestamp,
+            index,
+        });
+    });
+    parsed.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    const events = parsed.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
+    // Sender (merchant) and branchAddress (Z-BOX/partner shop) carry no
+    // recipient PII and are the only pickup signal — Packeta exposes no ETA.
+    const sender = clean(item.sender, 200) || null;
+    const pickupPoint = clean(item.branchAddress, 300) || null;
+    const deliveredAt = classified?.status === 'delivered' ? events[0]?.time ?? null : null;
+    if (!classified) {
+        return {
+            status: 'unknown',
+            last_status_text: clean(item.packetStatus, 500) || events[0]?.description || 'Tracking information received',
+            last_update: events[0]?.time ?? null,
+            expected_delivery: null,
+            timezone: 'Europe/Prague',
+            ...(sender ? { sender_name: sender } : {}),
+            ...(pickupPoint ? { pickup_point: pickupPoint } : {}),
+            events,
+        };
+    }
+    return {
+        status: classified.status,
+        current_stage: classified.stage,
+        // packetStatus is the backend's fixed English wording for the requested
+        // locale.
+        last_status_text: clean(item.packetStatus, 500) || events[0]?.description || 'Tracking information received',
+        last_update: events[0]?.time ?? null,
+        expected_delivery: null,
+        timezone: 'Europe/Prague',
+        ...(sender ? { sender_name: sender } : {}),
+        ...(pickupPoint ? { pickup_point: pickupPoint } : {}),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        events,
+    };
+}
+export class PacketaTracker {
+    timeoutMs;
+    fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Packeta timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizePacketaTrackingNumber(rawTrackingNumber);
+        const url = `${TRACKING_ENDPOINT}/${encodeURIComponent(trackingNumber)}/${TRACKING_LOCALE}`;
+        const { response, bytes } = await fetchBounded(url, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json, text/plain, */*',
+                'Accept-Language': 'en-US,en;q=0.9',
+                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+            },
+        }, {
+            provider: 'Packeta tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            retryTransient: true,
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        if (response.status === 404)
+            throw new NotFoundError('Packeta');
+        if (!response.ok)
+            throw new UpstreamHttpError('Packeta tracking', response.status);
+        return parsePacketaTrackingResponse(parseJsonBytes(bytes, 'Packeta tracking'), trackingNumber);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new PacketaTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'packeta',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/packeta/carrier.json

@@ -0,0 +1,90 @@
+{
+  "id": "packeta",
+  "displayName": "Packeta",
+  "aliases": [
+    "Zásilkovna",
+    "Zasilkovna",
+    "Packeta Slovakia",
+    "Z-BOX"
+  ],
+  "region": {
+    "countries": [
+      "CZ",
+      "SK",
+      "HU",
+      "RO",
+      "PL"
+    ]
+  },
+  "brand": {
+    "color": "#ba1b02"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "packeta",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "sender_name",
+    "pickup_point",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://tracking.packeta.com/en/{trackingNumber}",
+    "canaryUrl": "https://tracking.packeta.com/",
+    "shows": [
+      "status",
+      "history",
+      "sender_name",
+      "pickup_point",
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "sender_name",
+      "pickup_point",
+      "delivered_at"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "unavailable": [
+      "eta",
+      "location"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "tracking.packeta.com",
+        "packeta.com"
+      ],
+      "params": [
+        "id"
+      ]
+    },
+    {
+      "domains": [
+        "tracking.packeta.com"
+      ],
+      "path": "^/[a-z]{2}/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "packeta-1",
+      "pattern": "^Z\\d{10}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/packeta/numbers.json

@@ -0,0 +1,71 @@
+{
+  "carrier": "packeta",
+  "records": [
+    {
+      "number": "Z1234567890",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://docs.packeta.com/docs/packet-tracking/tracking"
+      },
+      "expect": {
+        "carrier": "packeta",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "Z3110953842",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php?suche=Z3110953842",
+        "date": "2023-06-05"
+      },
+      "expect": {
+        "carrier": "packeta",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "Z8328162946",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://help.orrs.de/6622/z%C3%A1silkovna-tracking-not-working"
+      },
+      "expect": {
+        "carrier": "packeta",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "Z8328162951",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://help.orrs.de/6622/z%C3%A1silkovna-tracking-not-working"
+      },
+      "expect": {
+        "carrier": "packeta",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "Z8360329994",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://help.orrs.de/6622/z%C3%A1silkovna-tracking-not-working"
+      },
+      "expect": {
+        "carrier": "packeta",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Packeta status vocabulary.
+ *
+ * Two independent maps, because Packeta reports status twice:
+ * - `packetStatusId` on the parcel, a closed numeric vocabulary. An unmapped id
+ *   is schema drift, so the result reports `unknown` rather than guessing.
+ * - The event sentences in `trackingDetails[].text`. There is no per-event
+ *   code; the request pins the locale to English and real parcels confirmed
+ *   these sentences are canned templates, so fixed substring matching is safe.
+ *   An unrecognized sentence keeps no stage: the sync classifies it and records
+ *   where the final stage came from.
+ *
+ * Provenance: derived from the prior-art client
+ * https://github.com/ha-parcel-integrations/ha-packeta (MIT). Only
+ * `packetStatusId` "3" (delivered) is live-confirmed there; the other ids are
+ * reconstructed. The event sentences were confirmed live on 2026-08-19 against
+ * real delivered parcels (values fictionalized in that project's fixtures).
+ */
+import type { ClassifiedStatus, Stage } from '../../core/status/index.js';
+/** The stage and status for a `packetStatusId`, or undefined when unmapped. */
+export declare function classifyPacketaStatus(code: string): ClassifiedStatus | undefined;
+/** The stage for one canned English event sentence, or null when unrecognized. */
+export declare function packetaEventStage(rawDescription: string): Stage | null;

package/dist/carriers/packeta/status.js

@@ -0,0 +1,40 @@
+const PACKET_STATUS = {
+    // TO_BE_PROCESSED
+    '997': { status: 'pending', stage: 'registered' },
+    // WAITING_FOR_DELIVERY (in warehouse)
+    '1': { status: 'in_transit', stage: 'in_transit' },
+    // ON_THE_WAY
+    '31': { status: 'in_transit', stage: 'in_transit' },
+    // READY_FOR_PICKUP
+    '2': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    // ISSUED_AND_ACCOUNTED (live-confirmed delivered wording:
+    // "The package has been delivered")
+    '3': { status: 'delivered', stage: 'delivered' },
+    // LOST_OR_UNKNOWN
+    '21': { status: 'exception', stage: 'failed_attempt' },
+};
+const EVENT_TEXT_STAGES = [
+    ['aware of your parcel and are waiting for the sender', 'registered'],
+    ['assigned a tracking number', 'registered'],
+    ['successfully received the parcel for transport', 'in_transit'],
+    ['on its way to the depot', 'in_transit'],
+    ['arrived at the depot', 'in_transit'],
+    ['has been handed over to the carrier', 'in_transit'],
+    ['on its way to you', 'out_for_delivery'],
+    ['ready for pickup', 'ready_for_pickup'],
+    ['the parcel is with you', 'delivered'],
+    ['investigating the status of the parcel', 'failed_attempt'],
+];
+/** The stage and status for a `packetStatusId`, or undefined when unmapped. */
+export function classifyPacketaStatus(code) {
+    return PACKET_STATUS[code];
+}
+/** The stage for one canned English event sentence, or null when unrecognized. */
+export function packetaEventStage(rawDescription) {
+    const value = rawDescription.toLocaleLowerCase('en-US');
+    for (const [substring, stage] of EVENT_TEXT_STAGES) {
+        if (value.includes(substring))
+            return stage;
+    }
+    return null;
+}

package/dist/carriers/packeta/statuses.json

@@ -0,0 +1,21 @@
+{
+  "carrier": "packeta",
+  "entries": [
+    { "code": "997", "language": "en", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "TO_BE_PROCESSED; reconstructed, not re-observed." },
+    { "code": "1", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "WAITING_FOR_DELIVERY (in warehouse); reconstructed." },
+    { "code": "31", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "ON_THE_WAY; reconstructed." },
+    { "code": "2", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "READY_FOR_PICKUP; reconstructed." },
+    { "code": "3", "wording": "The package has been delivered", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "ISSUED_AND_ACCOUNTED; the only packetStatusId confirmed against real delivered parcels." },
+    { "code": "21", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "LOST_OR_UNKNOWN; reconstructed." },
+    { "wording": "We are aware of your parcel and are waiting for the sender…", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "…assigned a tracking number…", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "…successfully received the parcel for transport…", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "The parcel is currently on its way to the depot.", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "…arrived at the depot…", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "The parcel has been handed over to the carrier…", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "…on its way to you…", "language": "en", "stage": "out_for_delivery", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "The parcel is ready for pickup…", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "The parcel is with you…", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." },
+    { "wording": "…investigating the status of the parcel…", "language": "en", "stage": "failed_attempt", "confirmedBy": "live", "firstSeen": "2026-08-19", "note": "Event sentence; substring match." }
+  ]
+}

package/dist/carriers/parcelforce/carrier.json

@@ -0,0 +1,47 @@
+{
+  "id": "parcelforce",
+  "displayName": "Parcelforce Worldwide",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "GB"
+    ]
+  },
+  "brand": {
+    "color": "#9d0f11"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.royalmail.com/track-your-item#/tracking-results/{trackingNumber}",
+    "canaryUrl": "https://www.royalmail.com/track-your-item",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "parcelforce.com"
+      ],
+      "params": [
+        "trackNumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "parcelforce-1",
+      "pattern": "^(?:EA|EB|EC|ED|EE|CP|GI)\\d{9}GB$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/parcelforce/numbers.json

@@ -0,0 +1,32 @@
+{
+  "carrier": "parcelforce",
+  "records": [
+    {
+      "number": "EC080250821GB",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.royalmail.com/royal-mail-you/intellectual-property-rights/linking-our-website"
+      },
+      "expect": {
+        "carrier": "parcelforce",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "GI049170518GB",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab10ab55824d015aa93bd4c",
+        "date": "2026-09-21"
+      },
+      "expect": {
+        "carrier": "parcelforce",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Planzer and Quickpac tracking.
+ *
+ * Planzer's own tracking app reads a keyless JSON API:
+ * `api.tracking.app.planzer.ch/api/v1/shipments/{shipment}/Pak`. Quickpac's
+ * 18-digit `44…` identifiers go through the same API and the same public page,
+ * so one adapter serves both carrier ids (see ./README.md).
+ *
+ * A shipment may carry several transport positions. A parcel number reads only
+ * the position whose `positionNumber` equals it, because the response can
+ * include positions of other shipments in the same delivery. A shipment number
+ * (the reply's own `shipmentNumber`) reads every position of that shipment.
+ *
+ * Shipments shared through a capability link are not in this API: they are
+ * served by `./shared`, chosen by the factory when the parcel has a tracking
+ * URL.
+ */
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+/**
+ * The shipment number the API expects. Planzer prints `reference.shipment`
+ * composites (`87979.0061660090`); only the shipment half is looked up, without
+ * its leading zeros. The app stores numbers without dots, so a 5-digit
+ * reference followed by a zero-padded 10-digit shipment is split the same way.
+ */
+export declare function planzerShipmentNumber(trackingNumber: string): string;
+/** Projects one `/shipments/{shipment}/Pak` payload. Pure: the offline tests target this. */
+export declare function parsePlanzerTrackingResponse(value: unknown, shipmentNumber: string): CarrierResult;
+export declare class PlanzerTracker {
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export declare function fetchPlanzer(trackingNumber: string): Promise<CarrierResult>;
+export declare const adapter: AdapterFactory;