universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/dpd/carrier.json

@@ -0,0 +1,111 @@
+{
+  "id": "dpd",
+  "displayName": "DPD",
+  "aliases": [
+    "DPD Switzerland",
+    "DPD (Schweiz) AG",
+    "myDPD"
+  ],
+  "region": {
+    "countries": [
+      "CH"
+    ]
+  },
+  "brand": {
+    "color": "#dc0032"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "dpd",
+    "requirements": [
+      {
+        "field": "dpdPostcode",
+        "validator": "swissPostcode",
+        "optional": true,
+        "label": "Delivery postcode",
+        "type": "text",
+        "placeholder": "8000",
+        "help": "Optional. DPD uses it to unlock verified scans and the delivery window.",
+        "pattern": "^[0-9]{4}$",
+        "maxLength": 4,
+        "inputMode": "numeric",
+        "autoComplete": "postal-code"
+      }
+    ],
+    "steps": [
+      "direct",
+      "page"
+    ],
+    "recognition": {
+      "rank": 70
+    }
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "sender_name",
+    "pickup_point",
+    "weight",
+    "delivered_at",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://www.dpdgroup.com/ch/mydpd/my-parcels/incoming?parcelNumber={trackingNumber}",
+    "canaryUrl": "https://www.dpdgroup.com/ch/mydpd/my-parcels/incoming",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "eta_window",
+      "sender_name",
+      "pickup_point",
+      "weight"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "eta_window",
+      "sender_name",
+      "pickup_point",
+      "weight",
+      "delivered_at",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "dpdgroup.com",
+        "dpd.com"
+      ],
+      "params": [
+        "parcelNumber",
+        "parcelnumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "dpd-2",
+      "pattern": "^06(?:0[6-9]|1\\d)\\d{10}$",
+      "confidence": "low",
+      "preferred": true
+    },
+    {
+      "id": "dpd-1",
+      "pattern": "^\\d{14}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/dpd/numbers.json

@@ -0,0 +1,43 @@
+{
+  "carrier": "dpd",
+  "records": [
+    {
+      "number": "06086216767970",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "dpd-fr",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to DPD, which stays one candidate among several."
+    },
+    {
+      "number": "01196812014637L",
+      "role": "quarantined",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to DPD, which no rule claims."
+    }
+  ]
+}

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

@@ -0,0 +1,39 @@
+/**
+ * DPD Switzerland status vocabulary.
+ *
+ * Three sources have to agree here. The myDPD guest API answers with a
+ * `parcelHistory[].description` / `status.description` enumeration
+ * (`DELIVERED`, `AVAILABLE_FOR_COLLECTION`, ...), which is the reliable key. A
+ * verified-postcode lookup adds `parcelEvents[].eventType` scan codes (`DEY`,
+ * `DLO`, ...). The rendered consignee page has no codes at all, only
+ * translated prose, so the page fallback is classified by wording in four
+ * languages.
+ *
+ * Only the values whose meaning is unambiguous receive an explicit stage.
+ * `PARCEL_HANDED`, `IN_TRANSIT` and `AT_DELIVERY_CENTER` deliberately yield no
+ * stage: they move the result status to `in_transit` but leave the event
+ * unmapped so the sync's classifier records the wording for review instead of
+ * this map inventing a milestone. Scan codes are mapped only where a live
+ * lookup paired them with an enumeration value (see `scanStage`).
+ *
+ * Provenance: the enumeration, the scan codes and their English labels are
+ * what the myDPD guest API returns for Swiss consignee lookups; the wording
+ * lists come from the public tracking page in en/de/fr/it.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../core/status/index.js';
+/** English labels for the guest API enumeration, used when the API sends no translation. */
+export declare const API_LABELS: Record<string, string>;
+/** Wording classifier for the rendered page, which carries no status codes. */
+export declare function wordingStatus(text: string, hasEvents: boolean): CarrierStatus;
+/** The result status for a guest API enumeration value, falling back to the wording. */
+export declare function apiStatus(description: unknown, statusText: string, hasEvents: boolean): CarrierStatus;
+/** The stage for a guest API enumeration value, or null when the value is not mapped. */
+export declare function apiStage(description: unknown): Stage | null;
+/** The stage for a guest API scan code, or null when the code is not mapped. */
+export declare function scanStage(code: string): Stage | null;
+/**
+ * "Delivery - Proof of delivery": DPD filing the proof minutes after DEY,
+ * with no place. Paperwork, not a movement of the parcel.
+ */
+export declare const PROOF_OF_DELIVERY_SCAN = "DEYY";

package/dist/carriers/dpd/status.js

@@ -0,0 +1,93 @@
+/** English labels for the guest API enumeration, used when the API sends no translation. */
+export const API_LABELS = {
+    ORDER_CREATED: 'Order created',
+    PARCEL_HANDED: 'Parcel handed to DPD',
+    IN_TRANSIT: 'Your parcel is on its way',
+    AT_DELIVERY_CENTER: 'At delivery center',
+    RETURN_TO_SENDER: 'Return to sender',
+    PARCEL_OUT_FOR_DELIVERY: 'Parcel out for delivery',
+    AVAILABLE_FOR_COLLECTION: 'Ready for collection',
+    UNSUCCESSFUL_DELIVERY_ATTEMPT: 'Unsuccessful delivery attempt',
+    DELIVERED: 'Delivered',
+    OTHER: 'Other tracking update',
+};
+/** Wording classifier for the rendered page, which carries no status codes. */
+export function wordingStatus(text, hasEvents) {
+    const value = text.toLocaleLowerCase('en-US');
+    if (['failed', 'not delivered', 'unable', 'problem', 'retour', 'returned']
+        .some((term) => value.includes(term)))
+        return 'exception';
+    if (['delivered', 'zugestellt', 'livré', 'consegnato']
+        .some((term) => value.includes(term)))
+        return 'delivered';
+    if (['out for delivery', 'delivery today', 'in zustellung', 'en cours de livraison']
+        .some((term) => value.includes(term)))
+        return 'out_for_delivery';
+    if (hasEvents || ['handed to dpd', 'on its way', 'arrived', 'depot', 'network']
+        .some((term) => value.includes(term)))
+        return 'in_transit';
+    if (['data received', 'information received', 'announced', 'übergeben']
+        .some((term) => value.includes(term)))
+        return 'pending';
+    return 'unknown';
+}
+/** The result status for a guest API enumeration value, falling back to the wording. */
+export function apiStatus(description, statusText, hasEvents) {
+    const key = typeof description === 'string' ? description.trim().toUpperCase() : '';
+    if (key === 'DELIVERED')
+        return 'delivered';
+    if (['PARCEL_OUT_FOR_DELIVERY', 'AVAILABLE_FOR_COLLECTION'].includes(key)) {
+        return 'out_for_delivery';
+    }
+    if (['RETURN_TO_SENDER', 'UNSUCCESSFUL_DELIVERY_ATTEMPT'].includes(key)) {
+        // A failed attempt is a retry, not terminal; a return is terminal but
+        // stays in the exception status with a returned stage (no returning status).
+        return key === 'RETURN_TO_SENDER' ? 'exception' : 'in_transit';
+    }
+    if (key === 'ORDER_CREATED')
+        return 'pending';
+    if (['PARCEL_HANDED', 'IN_TRANSIT', 'AT_DELIVERY_CENTER'].includes(key))
+        return 'in_transit';
+    return wordingStatus(statusText, hasEvents);
+}
+/** The stage for a guest API enumeration value, or null when the value is not mapped. */
+export function apiStage(description) {
+    const key = typeof description === 'string' ? description.trim().toUpperCase() : '';
+    if (key === 'AVAILABLE_FOR_COLLECTION')
+        return 'ready_for_pickup';
+    if (key === 'PARCEL_OUT_FOR_DELIVERY')
+        return 'out_for_delivery';
+    if (key === 'RETURN_TO_SENDER')
+        return 'returned';
+    if (key === 'UNSUCCESSFUL_DELIVERY_ATTEMPT')
+        return 'failed_attempt';
+    if (key === 'ORDER_CREATED')
+        return 'registered';
+    if (key === 'DELIVERED')
+        return 'delivered';
+    return null;
+}
+/**
+ * `parcelEvents[].eventType` scan codes. On 2026-09-26 a verified lookup
+ * listed ORI, DLI, DLO and DEY at the same wall clock as the `parcelHistory`
+ * enumeration named beside them. CCO has no twin; it ends customs clearance.
+ * ORI ("Origin depot - In") stays unmapped like its twin PARCEL_HANDED: the
+ * result stage then comes from the same wording as the scan's, and an import
+ * that cleared customs does not step back to accepted. Other codes stay
+ * unmapped.
+ */
+const SCAN_STAGES = {
+    CCO: 'in_transit', // "Customs - Out"
+    DLI: 'in_transit', // "Destination depot - Inbound", twin AT_DELIVERY_CENTER
+    DLO: 'out_for_delivery', // "Destination depot - Out for delivery", twin PARCEL_OUT_FOR_DELIVERY
+    DEY: 'delivered', // "Delivery - Delivered", twin DELIVERED
+};
+/** The stage for a guest API scan code, or null when the code is not mapped. */
+export function scanStage(code) {
+    return Object.hasOwn(SCAN_STAGES, code) ? SCAN_STAGES[code] : null;
+}
+/**
+ * "Delivery - Proof of delivery": DPD filing the proof minutes after DEY,
+ * with no place. Paperwork, not a movement of the parcel.
+ */
+export const PROOF_OF_DELIVERY_SCAN = 'DEYY';

package/dist/carriers/dpd/statuses.json

@@ -0,0 +1,144 @@
+{
+  "carrier": "dpd",
+  "entries": [
+    {
+      "code": "ORDER_CREATED",
+      "wording": "Order created",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "code": "PARCEL_HANDED",
+      "wording": "Parcel handed to DPD",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Moves the result to in_transit; no milestone of its own, so the event stays unmapped for the sync to classify. Its verified parcelEvents twin is ORI."
+    },
+    {
+      "code": "IN_TRANSIT",
+      "wording": "Your parcel is on its way",
+      "language": "en",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Moves the result to in_transit; no milestone of its own, so the event stays unmapped for the sync to classify."
+    },
+    {
+      "code": "AT_DELIVERY_CENTER",
+      "wording": "At delivery center",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Moves the result to in_transit; no milestone of its own, so the event stays unmapped for the sync to classify."
+    },
+    {
+      "code": "PARCEL_OUT_FOR_DELIVERY",
+      "wording": "Parcel out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "code": "AVAILABLE_FOR_COLLECTION",
+      "wording": "Ready for collection",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "The only value that unlocks the pickup-point name."
+    },
+    {
+      "code": "UNSUCCESSFUL_DELIVERY_ATTEMPT",
+      "wording": "Unsuccessful delivery attempt",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "A retry, not a terminal state: the result status stays in_transit."
+    },
+    {
+      "code": "RETURN_TO_SENDER",
+      "wording": "Return to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Terminal, reported with the exception status."
+    },
+    {
+      "code": "DELIVERED",
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": ""
+    },
+    {
+      "code": "OTHER",
+      "wording": "Other tracking update",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "The guest API's catch-all; neither a status nor a stage is derived from it."
+    },
+    {
+      "code": "CCO",
+      "wording": "Your parcel cleared customs successfully",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Customs - Out) with no parcelHistory twin. Its country is the UNDEFINED placeholder, so the scan has no place."
+    },
+    {
+      "code": "ORI",
+      "wording": "Your parcel arrived at our depot",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Origin depot - In), at the same instant as PARCEL_HANDED. Unmapped like its twin, so the event and the result stage both come from this wording; a stage here would disagree with the result stage and put accepted after customs on imports."
+    },
+    {
+      "code": "DLI",
+      "wording": "Your parcel arrived at our delivery depot",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Destination depot - Inbound), at the same instant as AT_DELIVERY_CENTER."
+    },
+    {
+      "code": "DLO",
+      "wording": "Your parcel is out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Destination depot - Out for delivery), at the same instant as PARCEL_OUT_FOR_DELIVERY."
+    },
+    {
+      "code": "DEY",
+      "wording": "Your parcel has been delivered successfully",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Delivery - Delivered), at the same instant as DELIVERED."
+    },
+    {
+      "code": "DEYY",
+      "wording": "We received the proof of delivery",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Scan code (Delivery - Proof of delivery), minutes after DEY with no place. Dropped when a delivery scan is listed or the enumeration is not DELIVERED; staged delivered only when it is the sole delivery evidence of a delivered parcel. Its podUrl is never kept."
+    }
+  ]
+}

package/dist/carriers/dpd-fr/adapter.d.ts

@@ -0,0 +1,42 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { ChallengeError, NotFoundError } from '../../core/errors/index.js';
+import { type CarrierResult } from '../../core/result/index.js';
+import type { StepRecorder } from '../../core/telemetry/index.js';
+import { TrawlClient } from '../../core/transport/index.js';
+/** Cloudflare interrupted the trace page with an interactive challenge. */
+export declare class DPDFranceChallengeError extends ChallengeError {
+    constructor(message?: string);
+}
+/** DPD France positively reports that it does not know the parcel number. */
+export declare class DPDFranceTrackingError extends NotFoundError {
+    constructor();
+}
+export declare function normalizeDPDFranceTrackingNumber(raw: string): string;
+export declare function dpdFranceTrackingUrl(raw: string): string;
+export declare function parseDPDFranceTrackingHtml(html: string, rawTrackingNumber: string): CarrierResult;
+export interface DPDFranceTrackerOptions {
+    timeoutMs?: number;
+    directTimeoutMs?: number;
+    /** Whole-lookup budget; defaults to both tiers plus the solver's own allowance. */
+    budgetMs?: number;
+    /** Legacy configuration seam kept for tests; production passes `trawl`. */
+    trawlUrl?: string;
+    fetcher?: typeof fetch;
+    trawl?: TrawlClient | null;
+    recorder?: StepRecorder;
+}
+export declare class DPDFranceTracker {
+    readonly timeoutMs: number;
+    readonly directTimeoutMs: number;
+    readonly budgetMs: number;
+    readonly trawlUrl: string;
+    private readonly fetcher?;
+    private readonly configuredTrawl?;
+    private readonly recorder?;
+    constructor(options?: DPDFranceTrackerOptions);
+    /** The browser service, resolved late so a malformed URL fails the tier, not construction. */
+    private browserService;
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+    private directGet;
+}
+export declare const adapter: AdapterFactory;