universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/dpd-fr/statuses.json

@@ -0,0 +1,325 @@
+{
+  "carrier": "dpd-fr",
+  "entries": [
+    {
+      "wording": "retour a l expediteur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "retourne a l expediteur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "sera retourne a l expediteur",
+      "language": "fr",
+      "stage": "returned",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "A future return is already reported as returned; checked before the delivery wording."
+    },
+    {
+      "wording": "reclamation",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "enquete est ouverte",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "echec de livraison",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "livraison impossible",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "n a pas pu etre livre",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "tentative de livraison",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "incident",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "anomalie",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "endommage",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "refuse",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "perdu",
+      "language": "fr",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "retard",
+      "language": "fr",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes exception."
+    },
+    {
+      "wording": "votre colis est livre",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes delivered."
+    },
+    {
+      "wording": "votre colis a ete livre",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes delivered."
+    },
+    {
+      "wording": "remis au destinataire",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes delivered."
+    },
+    {
+      "wording": "livraison effectuee",
+      "language": "fr",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes delivered."
+    },
+    {
+      "wording": "disponible en relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "disponible au relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "disponible en agence",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "disponible en consigne",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "attend en relais",
+      "language": "fr",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "en cours de livraison",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "en tournee de livraison",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "chauffeur a pris en charge",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes out_for_delivery."
+    },
+    {
+      "wording": "en preparation chez l expediteur",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes pending."
+    },
+    {
+      "wording": "informations concernant votre colis ont ete transmises",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes pending."
+    },
+    {
+      "wording": "donnees du colis transmises",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes pending."
+    },
+    {
+      "wording": "remis a dpd",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "pris en charge par dpd",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "en transit",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "arrive en france",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "arrive dans notre agence",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "prochaine agence",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "centre de tri",
+      "language": "fr",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-12",
+      "note": "Substring match on the accent-free wording; the result status becomes in_transit."
+    },
+    {
+      "wording": "de la livraison de son colis ce jour",
+      "language": "fr",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-18",
+      "note": "Same-day delivery notice sent to the recipient by SMS and by e-mail. It follows the delivery-round scan, so it must not move the parcel back to in_transit."
+    },
+    {
+      "wording": "pris en charge dans notre reseau",
+      "language": "fr",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-17",
+      "note": "Acceptance into the network; the result status becomes in_transit."
+    },
+    {
+      "wording": "de la prise en charge de son colis",
+      "language": "fr",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-17",
+      "note": "Acceptance notice sent to the recipient by SMS and by e-mail; the result status becomes in_transit."
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class DtdcTracker {
+    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/dtdc/adapter.js

@@ -0,0 +1,39 @@
+import { IndeterminateError, TransportError, UpstreamHttpError } 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 { normalizeDtdcNumber, parseDtdc } from './parser.js';
+// The current official MyDTDC app's anonymous tracking feed. Its deployed
+// assets/configs/prod.json names this host; the Flutter client calls this path.
+const ENDPOINT = 'https://ebookingbackend.dtdc.in/trackConsignment';
+export class DtdcTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeDtdcNumber(raw);
+        return runSteps({ carrier: 'dtdc', signal: context.signal, budgetMs: context.budgetMs ?? 15_000,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    try {
+                        const { bytes } = await fetchBounded(`${ENDPOINT}?reference_number=${number}`, { signal, headers: { Accept: 'application/json' } }, {
+                            provider: 'DTDC', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000, fetcher: this.options.fetcher,
+                        });
+                        return parseDtdc(parseJsonBytes(bytes, 'DTDC'), number);
+                    }
+                    catch (error) {
+                        // The feed answers unavailable references with a generic HTTP 400,
+                        // which does not prove absence. Endpoint 404s are not parcel absence.
+                        if (error instanceof UpstreamHttpError && error.status === 400)
+                            throw new IndeterminateError('DTDC', 'DTDC could not return shipment details', { cause: error });
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                            throw new TransportError('DTDC', 'DTDC tracking endpoint is unavailable', { cause: error });
+                        throw error;
+                    }
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new DtdcTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'dtdc', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/dtdc/carrier.json

@@ -0,0 +1,77 @@
+{
+  "id": "dtdc",
+  "displayName": "DTDC",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "IN"
+    ]
+  },
+  "brand": {
+    "color": "#0d237d"
+  },
+  "selectable": true,
+  "timezone": "Asia/Kolkata",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "dtdc",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://web.mydtdc.in/",
+    "canaryUrl": "https://web.mydtdc.in/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "addresses",
+      "contact_details",
+      "booking_details",
+      "unlabelled_weight"
+    ],
+    "unavailable": [
+      "eta",
+      "pickup_point"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "dtdc.com"
+      ],
+      "params": [
+        "trackingId"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "dtdc-1",
+      "pattern": "^N\\d{8}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dtdc-2",
+      "pattern": "^7[DX]\\d{9}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dtdc-3",
+      "pattern": "^[BDHPTUV]\\d{10}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/dtdc/numbers.json

@@ -0,0 +1,50 @@
+{
+  "carrier": "dtdc",
+  "records": [
+    {
+      "number": "7D119335452",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab70eab4f8ac906897c270d",
+        "date": "2026-09-26"
+      },
+      "expect": {
+        "carrier": "dtdc",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "N95614372",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "dtdc",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "T5001109884",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a9d03a2531e78ca983c377f",
+        "date": "2026-09-06"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dtdc"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to DTDC, which stays one candidate among several."
+    }
+  ]
+}

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

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

package/dist/carriers/dtdc/parser.js

@@ -0,0 +1,90 @@
+import { IndeterminateError, InputRequiredError, SchemaError } from '../../core/errors/index.js';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { epochMillisTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { dtdcStatus } from './status.js';
+const PROVIDER = 'DTDC';
+export function normalizeDtdcNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^[A-Z0-9]{8,20}$/.test(number))
+        throw new InputRequiredError(PROVIDER, 'number', 'DTDC requires an alphanumeric shipment reference');
+    return number;
+}
+function instant(value) {
+    // This feed supplies epoch milliseconds. Seconds must not become 1970 scans.
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1_000_000_000_000) {
+        throw new SchemaError(PROVIDER, 'DTDC returned an invalid event instant');
+    }
+    const parsed = epochMillisTime(value);
+    if (!parsed)
+        throw new SchemaError(PROVIDER, 'DTDC returned an invalid event instant');
+    return parsed.iso;
+}
+function event(raw, summary = false) {
+    if (!['forward', 'rto'].includes(String(raw.type)))
+        throw new SchemaError(PROVIDER, 'DTDC returned an unknown shipment leg');
+    const description = clean(summary ? raw.current_event_description : raw.event_description, 500) || clean(raw.status_external, 500);
+    if (!description)
+        throw new SchemaError(PROVIDER, 'DTDC returned an event with no description');
+    const mapped = dtdcStatus(clean(raw.status_external, 200)) ?? dtdcStatus(description);
+    const returning = raw.type === 'rto';
+    // The return leg still has ordinary pickup, transit and delivery movement.
+    // Only its completed delivery is a terminal return to the sender.
+    const stage = returning && mapped?.stage === 'delivered' ? 'returned' : mapped?.stage;
+    const location = clean(raw.location, 200);
+    const code = clean(raw.status_internal, 100);
+    return { description, time: instant(raw.timestamp), ...(location ? { location } : {}),
+        ...(stage ? { stage } : {}),
+        ...(code ? { provider_code: code } : {}), ...(returning ? { provider_leg: 'return' } : {}) };
+}
+export function parseDtdc(payload, trackingNumber) {
+    const requested = normalizeDtdcNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER);
+    if (payload.status === 'ERROR')
+        throw new IndeterminateError(PROVIDER, 'DTDC could not return shipment details');
+    if (payload.status !== 'OK' || !isRecord(payload.data))
+        throw new SchemaError(PROVIDER);
+    const data = payload.data;
+    if (!isRecord(data.consignment) || !Array.isArray(data.tracking) || data.tracking.length > 1000)
+        throw new SchemaError(PROVIDER);
+    const references = [data.consignment.AWBNo, data.consignment.referenceNumber]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .map(normalizeTrackingNumber);
+    if (!references.includes(requested))
+        throw new SchemaError(PROVIDER, 'DTDC returned a different shipment');
+    // A verified consignment may expose both its booking reference and original
+    // waybill. Empty history waybills are common; nonempty ones must match it.
+    const forwardAliases = new Set([requested, ...references]);
+    const returnAliases = new Set(forwardAliases);
+    if (typeof data.rto_awb_num === 'string' && data.rto_awb_num)
+        returnAliases.add(normalizeTrackingNumber(data.rto_awb_num));
+    const snapshot = event(data, true);
+    const events = [snapshot];
+    const seen = new Set([JSON.stringify(snapshot)]);
+    for (const scan of data.tracking) {
+        if (!isRecord(scan))
+            throw new SchemaError(PROVIDER, 'DTDC returned an incomplete history row');
+        const waybill = clean(scan.awb_number, 64);
+        const aliases = scan.type === 'rto' ? returnAliases : forwardAliases;
+        if (waybill && !aliases.has(normalizeTrackingNumber(waybill)))
+            throw new SchemaError(PROVIDER, 'DTDC returned mixed shipment history');
+        const parsed = event(scan);
+        const key = JSON.stringify(parsed);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(parsed);
+        }
+    }
+    events.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const wording = snapshot.description;
+    const mapped = dtdcStatus(clean(data.status_external, 200)) ?? dtdcStatus(wording);
+    const returning = data.type === 'rto';
+    const returned = returning && mapped?.stage === 'delivered';
+    return { status: returned ? 'exception' : mapped?.status ?? 'unknown',
+        ...(mapped ? { current_stage: returned ? 'returned' : mapped.stage } : {}),
+        last_status_text: wording, last_update: snapshot.time, timezone: 'Asia/Kolkata',
+        ...(mapped?.stage === 'delivered' && !returning ? { delivered_at: snapshot.time } : {}),
+        events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/dtdc/status.js

@@ -0,0 +1,15 @@
+const STATUS = new Map([
+    ['Pickup Awaited', { status: 'pending', stage: 'registered' }],
+    ['Pickup Scheduled', { status: 'pending', stage: 'registered' }],
+    ['Booked', { status: 'pending', stage: 'registered' }],
+    ['Booked at Origin Branch', { status: 'pending', stage: 'registered' }],
+    ['Picked Up', { status: 'in_transit', stage: 'accepted' }],
+    ['Pickup Completed', { status: 'in_transit', stage: 'accepted' }],
+    ['In Transit', { status: 'in_transit', stage: 'in_transit' }],
+    ['Out For Delivery', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['Delivered', { status: 'delivered', stage: 'delivered' }],
+    ['RTO Booked', { status: 'exception', stage: 'exception' }],
+]);
+export function dtdcStatus(wording) {
+    return STATUS.get(wording);
+}