universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/delhivery/adapter.js

@@ -0,0 +1,36 @@
+import { 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 { normalizeDelhiveryNumber, parseDelhivery } from './parser.js';
+// Anonymous consumer feed with independently checked identity-bound responses.
+// Prior endpoint lead: https://github.com/ha-parcel-integrations/ha-delhivery
+const ENDPOINT = 'https://dlv-api.delhivery.com/v3/unified-tracking-new';
+export class DelhiveryTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeDelhiveryNumber(raw);
+        return runSteps({ carrier: 'delhivery', budgetMs: context.budgetMs ?? 15_000,
+            signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    let bytes;
+                    try {
+                        ({ bytes } = await fetchBounded(`${ENDPOINT}?wbn=${number}`, { signal,
+                            headers: { Accept: 'application/json', Origin: 'https://www.delhivery.com', Referer: 'https://www.delhivery.com/' },
+                        }, { provider: 'Delhivery', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000, fetcher: this.options.fetcher }));
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                            throw new TransportError('Delhivery', 'Delhivery tracking endpoint is unavailable', { cause: error });
+                        throw error;
+                    }
+                    return parseDelhivery(parseJsonBytes(bytes, 'Delhivery'), number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new DelhiveryTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'delhivery', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/delhivery/carrier.json

@@ -0,0 +1,50 @@
+{
+  "id": "delhivery",
+  "displayName": "Delhivery",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "IN"
+    ]
+  },
+  "brand": {
+    "color": "#ed4136"
+  },
+  "selectable": true,
+  "timezone": "Asia/Kolkata",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "delhivery",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history"
+  ],
+  "portal": {
+    "url": "https://www.delhivery.com/tracking",
+    "canaryUrl": "https://www.delhivery.com/tracking",
+    "shows": [
+      "status",
+      "history"
+    ],
+    "scraped": [
+      "status",
+      "history"
+    ],
+    "discarded": [
+      "recipient"
+    ],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "delhivery-1",
+      "pattern": "^\\d{13,14}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/delhivery/numbers.json

@@ -0,0 +1,108 @@
+{
+  "carrier": "delhivery",
+  "records": [
+    {
+      "number": "1623110010010",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/gauravsoti1/c2dc7e709401e89be5cf5701c917dd97"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Delhivery, which stays one candidate among several."
+    },
+    {
+      "number": "2827799099172",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab100770c4cdb8f7f45f673",
+        "date": "2026-09-21"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Delhivery, which stays one candidate among several."
+    },
+    {
+      "number": "32076610152736",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.consumercomplaints.in/delhivery-b103998",
+        "date": "2026-07-03"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Delhivery, which stays one candidate among several."
+    },
+    {
+      "number": "53424110007383",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab4b519710b8518846edbec",
+        "date": "2026-09-24"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Delhivery, which stays one candidate among several."
+    },
+    {
+      "number": "64941010000022",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aad2f27c5bf54f42be24f59",
+        "date": "2026-09-18"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Delhivery, which stays one candidate among several."
+    }
+  ]
+}

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

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

package/dist/carriers/delhivery/parser.js

@@ -0,0 +1,81 @@
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { isoTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyDelhiveryStatus } from './status.js';
+function scanTime(value) {
+    const raw = clean(value, 64);
+    // A calendar day is not a midnight scan. Require the supplied civil clock
+    // before applying the feed's India timezone to an offset-less timestamp.
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/.test(raw)
+        ? isoTime(raw, 'Asia/Kolkata') : null;
+}
+export function normalizeDelhiveryNumber(raw) {
+    const number = raw.replace(/[\s.-]/g, '');
+    if (!/^\d{13,14}$/.test(number))
+        throw new TypeError('Delhivery requires a thirteen- or fourteen-digit waybill');
+    return number;
+}
+export function parseDelhivery(payload, number) {
+    const requested = normalizeDelhiveryNumber(number);
+    if (!isRecord(payload) || payload.statusCode !== 200 || !Array.isArray(payload.data) || payload.data.length > 100)
+        throw new SchemaError('Delhivery');
+    if (!payload.data.length && payload.message === 'invalid AWB or very old package')
+        throw new NotFoundError('Delhivery');
+    const matches = payload.data.filter(isRecord).filter(item => clean(item.awb, 64) === requested);
+    if (matches.length !== 1)
+        throw new SchemaError('Delhivery', 'Delhivery did not return one matching shipment');
+    const item = matches[0];
+    if (!isRecord(item.status) || !Array.isArray(item.trackingStates))
+        throw new SchemaError('Delhivery');
+    const description = clean(item.status.status, 200);
+    if (!description)
+        throw new IndeterminateError('Delhivery', 'Delhivery returned no current status');
+    const mapped = classifyDelhiveryStatus(description);
+    const updated = scanTime(item.status.statusDateTime);
+    const currentTimeText = clean(item.status.statusDateTime, 64);
+    const events = [];
+    const seen = new Set();
+    // Only completed scans become events. State labels without scans are the
+    // website's future progress rail and must never claim movement.
+    for (const state of item.trackingStates.slice(0, 100)) {
+        if (!isRecord(state))
+            throw new SchemaError('Delhivery', 'Delhivery returned an incomplete tracking state');
+        if (state.scans === undefined)
+            continue;
+        if (!Array.isArray(state.scans))
+            throw new SchemaError('Delhivery', 'Delhivery returned invalid scan history');
+        for (const scan of state.scans.slice(0, 100)) {
+            if (!isRecord(scan))
+                throw new SchemaError('Delhivery', 'Delhivery returned an incomplete scan row');
+            if (events.length >= 500)
+                continue;
+            const label = clean(scan.scan, 200);
+            if (!label)
+                throw new SchemaError('Delhivery', 'Delhivery returned a scan with no description');
+            const time = scanTime(scan.scanDateTime);
+            const timeText = clean(scan.scanDateTime, 64);
+            const location = clean(scan.cityLocation, 160);
+            const key = `${time?.timestamp ?? timeText}\u0000${label}\u0000${location}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const classified = classifyDelhiveryStatus(label);
+            events.push({ description: label, ...(time ? { time: time.iso } : timeText ? { provider_time_text: timeText } : {}), ...(location ? { location } : {}),
+                ...(classified ? { stage: classified.stage } : {}) });
+        }
+    }
+    // Repeated scan labels cannot bind a summary timestamp to a particular
+    // historical location. Keep the dated status snapshot separate.
+    if (!updated || !events.some(event => event.time && Date.parse(event.time) === updated.timestamp
+        && event.description?.toUpperCase() === description.toUpperCase())) {
+        events.unshift({ description, ...(updated ? { time: updated.iso } : currentTimeText ? { provider_time_text: currentTimeText } : {}),
+            ...(mapped ? { stage: mapped.stage } : {}), summary_snapshot: true });
+    }
+    const dated = events.filter(event => event.time).sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const undated = events.filter(event => !event.time);
+    return { status: mapped?.status ?? 'unknown', ...(mapped ? { current_stage: mapped.stage } : {}),
+        last_status_text: description, last_update: updated?.iso ?? null, expected_delivery: null,
+        ...(mapped?.status === 'delivered' && updated ? { delivered_at: updated.iso } : {}),
+        timezone: 'Asia/Kolkata', events: [...dated, ...undated].slice(0, 100) };
+}

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

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

package/dist/carriers/delhivery/status.js

@@ -0,0 +1,11 @@
+const statuses = {
+    DELIVERED: { status: 'delivered', stage: 'delivered' },
+    'OUT FOR DELIVERY': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'IN TRANSIT': { status: 'in_transit', stage: 'in_transit' },
+    'PICKED UP': { status: 'in_transit', stage: 'accepted' },
+    MANIFESTED: { status: 'pending', stage: 'registered' },
+    'RTO DELIVERED': { status: 'exception', stage: 'returned' },
+};
+export function classifyDelhiveryStatus(value) {
+    return statuses[value.toUpperCase()];
+}

package/dist/carriers/delhivery/statuses.json

@@ -0,0 +1,11 @@
+{
+  "carrier": "delhivery",
+  "entries": [
+    {
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/delivengo/carrier.json

@@ -0,0 +1,56 @@
+{
+  "id": "delivengo",
+  "displayName": "Delivengo",
+  "aliases": [
+    "Delivengo Easy"
+  ],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#ffcf00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "la-poste",
+    "steps": [
+      "direct",
+      "retry"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://www.laposte.fr/outils/suivre-vos-envois?code={trackingNumber}",
+    "canaryUrl": "https://www.laposte.fr/outils/suivre-vos-envois",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "recipient_name",
+      "recipient_address"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address"
+    ],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": []
+}

package/dist/carriers/delivengo/numbers.json

@@ -0,0 +1,31 @@
+{
+  "carrier": "delivengo",
+  "records": [
+    {
+      "number": "LD156008025FR",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-10",
+      "expect": {
+        "carrier": "la-poste",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format. Filed under Delivengo; detection selects La Poste / Colissimo."
+    },
+    {
+      "number": "LL016042860FR",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/66fbba757cd91d06a7aef774",
+        "date": "2024-10-01"
+      },
+      "expect": {
+        "carrier": "la-poste",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Delivengo; detection selects La Poste. Parcel to Sweden."
+    }
+  ]
+}

package/dist/carriers/delivengo/statuses.json

@@ -0,0 +1,5 @@
+{
+  "carrier": "delivengo",
+  "entries": [],
+  "gap": "No Delivengo status vocabulary has been observed. The public endpoint answered the one published sample with an access error rather than usable history, so routing and parsing rely on the shared La Poste map in carriers/la-poste/statuses.json."
+}

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

@@ -0,0 +1,70 @@
+/**
+ * DHL Paket and tracked mail, through the public recipient endpoint behind
+ * www.dhl.de (`/int-verfolgen/data`).
+ *
+ * The lookup establishes a cookie and CSRF session on `/config`, then reads
+ * `/search` with the same `verfolgen-CSRF-token` and `verfolgen-wg` headers
+ * DHL's own recipient page sends. Cookies stay in memory. A rejected or
+ * expired session, and an interrupted read, get one fresh HTTP session inside
+ * the `direct` step; only then does the `trawl` step ask the private browser
+ * service for a solved session, whose cookies and user agent seed a new HTTP
+ * session. Rate limits and server errors stay errors: they are never routed
+ * through a browser.
+ *
+ * DHL's business API credentials are not needed for this public flow.
+ */
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { ChallengeError, type CarrierErrorOptions } 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';
+export declare function normalizeDHLTrackingNumber(raw: string): string;
+export declare function dhlTrackingUrl(number: string): string;
+/** Parse only public status fields: never persist recipient, address, signature or service data. */
+export declare function parseDHLTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+/**
+ * DHL answered with a redirect, an unauthorized status or a non-JSON body:
+ * the session is no longer accepted and has to be established again, from a
+ * browser when plain HTTP keeps being refused.
+ */
+export declare class DHLSessionError extends ChallengeError {
+    constructor(options?: CarrierErrorOptions);
+}
+export interface DHLTrackerOptions {
+    /** Budget for one browser solve; also the ceiling for the whole lookup. */
+    timeoutMs?: number;
+    /** Budget for a single HTTP request of the direct session. */
+    directTimeoutMs?: number;
+    budgetMs?: number;
+    /** The host's browser service. Preferred over `trawlUrl`. */
+    trawl?: TrawlClient | null;
+    /** Browser service URL, for the host's default constructor and for tests. */
+    trawlUrl?: string;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+    /** Clock used for the session age; injectable for tests. */
+    now?: () => number;
+}
+export declare class DHLTracker {
+    readonly timeoutMs: number;
+    readonly directTimeoutMs: number;
+    readonly budgetMs: number;
+    readonly trawlUrl: string;
+    private readonly trawl;
+    private readonly fetcher?;
+    private readonly recorder;
+    private readonly serialize;
+    private readonly now;
+    private session;
+    private sessionOpenedAt;
+    constructor(options?: DHLTrackerOptions);
+    private open;
+    /** Lookups share one session, so two parcels never renew it at the same time. */
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+    private lookup;
+    /** The direct session, renewing a stale one or an interrupted read once. */
+    private direct;
+    /** A solved browser session, replayed over HTTP with its cookies and user agent. */
+    private browser;
+}
+export declare const adapter: AdapterFactory;