universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/hermes-de/adapter.js

@@ -0,0 +1,168 @@
+import { DateTime } from 'luxon';
+import { recognizeFromLookup } from '../../core/adapter/index.js';
+import { InputRequiredError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { hermesGermanyMilestone, IGNORED_BOOKING_STATUS } from './status.js';
+// Public recipient protocol inspected 2026-09-08:
+// https://gcp-prd.my-deliveries.de/tnt/bundle/tnt-bundle-v2.js
+// Separate from Hermes Einrichtungs-Service (myhes.de). The postcode-protected
+// address endpoint is deliberately not called.
+const API = 'https://api.my-deliveries.de/tnt/v2/shipments/search/';
+const PROVIDER = 'Hermes Germany tracking';
+const CARRIER = 'Hermes Germany';
+const DEFAULT_TIMEOUT_MS = 15_000;
+export { STATUSES } from './status.js';
+function etaDate(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return new Date(value).toISOString().slice(0, 10);
+    }
+    const raw = clean(value, 64);
+    if (!raw)
+        return null;
+    const parsed = DateTime.fromISO(raw, { setZone: true });
+    if (parsed.isValid)
+        return parsed.toISODate();
+    const millis = Date.parse(raw);
+    return Number.isFinite(millis) ? new Date(millis).toISOString().slice(0, 10) : null;
+}
+/** Kept as a named class: the grouped live suite asserts this error's name. */
+export class HermesGermanyTrackingError extends NotFoundError {
+    constructor() {
+        super(CARRIER);
+        this.name = 'HermesGermanyTrackingError';
+    }
+}
+export function normalizeHermesGermanyNumber(raw) {
+    const value = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^(?=.*\d)[A-Z0-9]{8,20}$/.test(value)) {
+        throw new InputRequiredError(CARRIER, 'an 8-to-20-character tracking number', 'Hermes Germany requires an 8-to-20-character tracking number');
+    }
+    return value;
+}
+export function parseHermesGermanyResponse(payload, trackingNumber) {
+    const requested = normalizeHermesGermanyNumber(trackingNumber);
+    if (!Array.isArray(payload) || payload.some((entry) => !isRecord(entry))) {
+        throw new SchemaError(CARRIER, 'Hermes Germany returned an invalid tracking response');
+    }
+    if (!payload.length)
+        throw new HermesGermanyTrackingError();
+    const parcels = payload.filter((entry) => entry.barcode === requested);
+    if (parcels.length !== 1)
+        throw new SchemaError(CARRIER, 'Hermes Germany returned a different or ambiguous shipment');
+    const progress = parcels[0].parcelProgress;
+    if (!Array.isArray(progress) || !progress.length || progress.length > 500) {
+        throw new SchemaError(CARRIER, 'Hermes Germany returned an invalid tracking history');
+    }
+    const seen = new Set();
+    const events = [];
+    for (const entry of progress) {
+        if (!isRecord(entry) || typeof entry.timestamp !== 'string'
+            || typeof entry.parcelStatus !== 'string' || !/^[A-Z_]{1,64}$/.test(entry.parcelStatus)) {
+            throw new SchemaError(CARRIER, 'Hermes Germany returned an invalid tracking event');
+        }
+        const date = DateTime.fromISO(entry.timestamp, { zone: 'Europe/Berlin', setZone: true });
+        if (!date.isValid)
+            throw new SchemaError(CARRIER, 'Hermes Germany returned an invalid event date');
+        const time = date.toUTC().toISO();
+        const identity = `${time}|${entry.parcelStatus}`;
+        if (seen.has(identity) || IGNORED_BOOKING_STATUS.has(entry.parcelStatus))
+            continue;
+        seen.add(identity);
+        const metadata = hermesGermanyMilestone(entry.parcelStatus);
+        // historyText is the carrier's display wording; the `status` field only
+        // carries generic HAPPY/FINISHED buckets and is never display text.
+        const rawText = clean(entry.historyText);
+        events.push({
+            timestamp: date.toMillis(),
+            metadata,
+            event: {
+                time,
+                description: rawText || metadata?.description || 'Hermes tracking update',
+                stage: metadata?.stage ?? 'in_transit',
+                provider_code: entry.parcelStatus,
+            },
+        });
+    }
+    events.sort((a, b) => b.timestamp - a.timestamp);
+    const latest = events[0];
+    if (!latest)
+        throw new HermesGermanyTrackingError();
+    const parcel = parcels[0];
+    const attributes = isRecord(parcel.parcelAttributes) ? parcel.parcelAttributes : {};
+    const atg = isRecord(parcel.atg) ? parcel.atg : {};
+    const sender = clean(atg.companyName) || null;
+    const eta = etaDate(parcel.eta ?? parcel.deliveryForecast ?? attributes.deliveredTimestamp);
+    const deliveredByCode = latest.metadata?.status === 'delivered';
+    const deliveredByFlag = attributes.delivered === true;
+    const delivered = deliveredByCode || deliveredByFlag;
+    if (!latest.metadata && !delivered) {
+        return {
+            status: 'unknown',
+            last_status_text: latest.event.description,
+            last_update: latest.event.time,
+            expected_delivery: null,
+            timezone: 'Europe/Berlin',
+            ...(sender ? { sender_name: sender } : {}),
+            events: events.slice(0, 100).map(({ event }) => event),
+        };
+    }
+    const status = delivered ? 'delivered' : latest.metadata.status;
+    const stage = latest.metadata?.stage ?? (delivered ? 'delivered' : 'in_transit');
+    const deliveredAt = delivered ? latest.event.time : null;
+    return {
+        status,
+        current_stage: stage,
+        last_status_text: latest.event.description,
+        last_update: latest.event.time,
+        expected_delivery: delivered ? null : eta,
+        timezone: 'Europe/Berlin',
+        ...(sender ? { sender_name: sender } : {}),
+        ...(deliveredAt && status === 'delivered' ? { delivered_at: deliveredAt } : {}),
+        events: events.slice(0, 100).map(({ event }) => event),
+    };
+}
+export class HermesGermanyTracker {
+    timeoutMs;
+    #fetcher;
+    constructor(options = {}) {
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher } = typeof options === 'number'
+            ? { timeoutMs: options, fetcher: undefined }
+            : options;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new TypeError('Hermes Germany timeout must be positive');
+        this.timeoutMs = timeoutMs;
+        this.#fetcher = fetcher;
+    }
+    async fetch(trackingNumber) {
+        const number = normalizeHermesGermanyNumber(trackingNumber);
+        const { response, bytes } = await fetchBounded(`${API}${encodeURIComponent(number)}`, {
+            headers: {
+                Accept: 'application/json',
+                'X-Language': 'de',
+                Referer: 'https://www.myhermes.de/',
+                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+            },
+        }, {
+            provider: PROVIDER,
+            timeoutMs: this.timeoutMs,
+            maxBytes: 750_000,
+            allowHttpError: true,
+            ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
+        });
+        if (response.status === 404)
+            throw new HermesGermanyTrackingError();
+        if (!response.ok)
+            throw new UpstreamHttpError(PROVIDER, response.status);
+        return parseHermesGermanyResponse(parseJsonBytes(bytes, PROVIDER), number);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new HermesGermanyTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'hermes-de',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+        recognize: (number) => recognizeFromLookup(() => tracker.fetch(number)),
+    };
+};

package/dist/carriers/hermes-de/carrier.json

@@ -0,0 +1,90 @@
+{
+  "id": "hermes-de",
+  "displayName": "Hermes Germany",
+  "aliases": [
+    "myHermes",
+    "Hermes Germany GmbH"
+  ],
+  "region": {
+    "countries": [
+      "DE"
+    ]
+  },
+  "brand": {
+    "color": "#0091cd"
+  },
+  "selectable": true,
+  "timezone": "Europe/Berlin",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "hermes-de",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 40
+    }
+  },
+  "capabilities": [
+    "history",
+    "eta",
+    "sender_name",
+    "delivered_at",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://www.myhermes.de/empfangen/sendungsverfolgung/sendungsinformation#{trackingNumber}",
+    "canaryUrl": "https://www.myhermes.de/empfangen/sendungsverfolgung/",
+    "shows": [
+      "status",
+      "history",
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "delivery_instructions"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "eta",
+      "sender_name",
+      "delivered_at",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "delivery_instructions"
+    ],
+    "unavailable": [
+      "location"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "myhermes.de"
+      ],
+      "params": [
+        "TrackID",
+        "trackingNumber",
+        "sendungsId"
+      ],
+      "fragment": "^([A-Z0-9]{8,20})(?:$|[?&])"
+    }
+  ],
+  "detection": [
+    {
+      "id": "hermes-de-1",
+      "pattern": "^H\\d{15,19}$",
+      "confidence": "high"
+    },
+    {
+      "id": "hermes-de-2",
+      "pattern": "^\\d{14}$",
+      "confidence": "low",
+      "checksum": "hermes"
+    }
+  ]
+}

package/dist/carriers/hermes-de/numbers.json

@@ -0,0 +1,125 @@
+{
+  "carrier": "hermes-de",
+  "records": [
+    {
+      "number": "02180171003654",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php?suche_carrier=hermes"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "dpd-fr",
+          "ciblex",
+          "hermes-de",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Hermes Germany, which stays one candidate among several."
+    },
+    {
+      "number": "02310181006981",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php?suche_carrier=hermes"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "dpd-fr",
+          "ciblex",
+          "hermes-de",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Hermes Germany, which stays one candidate among several."
+    },
+    {
+      "number": "1071247368",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://de.trustpilot.com/reviews/6aa6c8e1e6ef84f3d9de84c3",
+        "date": "2026-09-13"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Hermes Germany, which no rule claims for this shape."
+    },
+    {
+      "number": "11204181008466",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php?suche_carrier=hermes"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "dpd-fr",
+          "ciblex",
+          "hermes-de",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Hermes Germany, which stays one candidate among several."
+    },
+    {
+      "number": "39181147009513",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php?suche_carrier=hermes"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "ciblex",
+          "hermes-de",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Hermes Germany, which stays one candidate among several."
+    },
+    {
+      "number": "H1234567890123456789",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "hermes-de",
+        "confidence": "high"
+      },
+      "note": "Invented H-prefixed number matching the Hermes Germany shape."
+    }
+  ]
+}

package/dist/carriers/hermes-de/status.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hermes Germany status classification.
+ *
+ * The public recipient service labels every history row with a stable
+ * `parcelStatus` enum, so this carrier is mapped by code alone: no wording
+ * rules, no language guessing. `description` is the fallback text used when the
+ * row carries no `historyText` of its own.
+ *
+ * A code that is not in this map is deliberately left unclassified. The adapter
+ * then reports the shipment as `unknown` rather than inventing a stage, and the
+ * sync records the wording for review.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface Milestone {
+    stage: Stage;
+    status: CarrierStatus;
+    description: string;
+}
+/** `parcelStatus` → milestone, read from the public recipient bundle on 2026-09-08. */
+export declare const STATUSES: Record<string, Milestone>;
+export declare const IGNORED_BOOKING_STATUS: Set<string>;
+/** The milestone for a `parcelStatus`, or undefined when the code is not mapped. */
+export declare function hermesGermanyMilestone(parcelStatus: string): Milestone | undefined;

package/dist/carriers/hermes-de/status.js

@@ -0,0 +1,52 @@
+function milestone(stage, status, description) {
+    return { stage, status, description };
+}
+/** `parcelStatus` → milestone, read from the public recipient bundle on 2026-09-08. */
+export const STATUSES = {
+    ANNOUNCED: milestone('registered', 'pending', 'Shipment announced to Hermes'),
+    ORDER_INFO_RECEIVED: milestone('registered', 'pending', 'Shipment announced to Hermes'),
+    PREANNOUNCED: milestone('registered', 'pending', 'Shipment announced to Hermes'),
+    PARCELSHOP_DROP_OFF: milestone('registered', 'pending', 'Dropped off at a ParcelShop'),
+    ATG_OUT_OF_WAREHOUSE: milestone('registered', 'pending', 'Sender preparing handover to Hermes'),
+    HANDED_OVER: milestone('accepted', 'in_transit', 'Shipment handed to Hermes'),
+    HANDED_OVER_TO_HERMES: milestone('accepted', 'in_transit', 'Shipment handed to Hermes'),
+    TAKEN_OVER_BY_HERMES: milestone('accepted', 'in_transit', 'Shipment collected by Hermes'),
+    PICKED_UP: milestone('accepted', 'in_transit', 'Shipment collected by Hermes'),
+    SHIPMENT_PICKED_UP: milestone('accepted', 'in_transit', 'Shipment collected by Hermes'),
+    PARCELSHOP_COLLECTED_BY_DRIVER: milestone('accepted', 'in_transit', 'Shipment collected by Hermes'),
+    ARRIVED_IN_DESTINATION_REGION: milestone('in_transit', 'in_transit', 'Shipment arrived in the destination region'),
+    ARRIVED_AT_DEPOT: milestone('in_transit', 'in_transit', 'Shipment arrived at the depot'),
+    ARRIVED_AT_DELIVERY_DEPOT: milestone('in_transit', 'in_transit', 'Shipment arrived at the delivery depot'),
+    ARRIVED_IN_DESTINATION_REGION_V2: milestone('in_transit', 'in_transit', 'Shipment arrived in the destination region'),
+    IN_TRANSIT: milestone('in_transit', 'in_transit', 'Shipment in transit'),
+    SORTED: milestone('in_transit', 'in_transit', 'Shipment sorted at the hub'),
+    DELIVERY_TOUR_STARTED: milestone('out_for_delivery', 'out_for_delivery', 'Out for delivery'),
+    OUT_FOR_DELIVERY: milestone('out_for_delivery', 'out_for_delivery', 'Out for delivery'),
+    NEXT_STOP: milestone('out_for_delivery', 'out_for_delivery', 'Courier is at the next stop'),
+    DELIVERED: milestone('delivered', 'delivered', 'Delivered'),
+    DELIVERED_HOMEDELIVERY: milestone('delivered', 'delivered', 'Delivered'),
+    DELIVERED_NEIGHBOUR: milestone('delivered', 'delivered', 'Delivered to a neighbour'),
+    DELIVERED_DROPOFF: milestone('delivered', 'delivered', 'Delivered to the agreed safe place'),
+    DELIVERED_MAILBOX: milestone('delivered', 'delivered', 'Delivered to the mailbox'),
+    DELIVERED_PARCELSHOP: milestone('delivered', 'delivered', 'Collected at the ParcelShop'),
+    DELIVERED_PARCELBOX: milestone('delivered', 'delivered', 'Delivered to the parcel box'),
+    PICKED_UP_BY_RECIPIENT: milestone('delivered', 'delivered', 'Collected by the recipient'),
+    COLLECTED: milestone('delivered', 'delivered', 'Collected by the recipient'),
+    READY_FOR_PICKUP: milestone('ready_for_pickup', 'out_for_delivery', 'Ready for collection'),
+    PARCELSHOP_ITEMS_FOR_COLLECTION: milestone('ready_for_pickup', 'out_for_delivery', 'Ready for collection at the ParcelShop'),
+    READY_FOR_COLLECTION: milestone('ready_for_pickup', 'out_for_delivery', 'Ready for collection'),
+    DELIVERY_FAILED: milestone('failed_attempt', 'exception', 'Delivery attempt unsuccessful'),
+    NOT_DELIVERABLE: milestone('exception', 'exception', 'Shipment not deliverable'),
+    UNKNOWN_WHEREABOUTS: milestone('exception', 'exception', 'Shipment whereabouts unknown'),
+    RETURN_TO_SENDER: milestone('returned', 'exception', 'Returning to sender'),
+    RETURN_DELIVERED_TO_SENDER: milestone('returned', 'exception', 'Returned to sender'),
+    RETURN: milestone('returned', 'exception', 'Returning to sender'),
+    RETOURE_DELIVERED: milestone('returned', 'exception', 'Returned to sender'),
+};
+// Pre-announcement preference bookings fire before collection and must never
+// move the parcel backwards on their own.
+export const IGNORED_BOOKING_STATUS = new Set(['EDL_BOOKED_DROPOFF']);
+/** The milestone for a `parcelStatus`, or undefined when the code is not mapped. */
+export function hermesGermanyMilestone(parcelStatus) {
+    return Object.hasOwn(STATUSES, parcelStatus) ? STATUSES[parcelStatus] : undefined;
+}