universal-parcel-scraper 0.49.0-main.533 → 0.49.0-main.543
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE +2 -1
- package/README.md +1 -1
- package/dist/app.d.ts +6 -3
- package/dist/app.js +6 -3
- package/dist/carriers/chronopost/status.d.ts +3 -0
- package/dist/carriers/chronopost/status.js +20 -1
- package/dist/carriers/chronopost/statuses.json +19 -1
- package/dist/carriers/dhl-express/adapter.d.ts +1 -1
- package/dist/carriers/dhl-express/adapter.js +7 -23
- package/dist/carriers/dhl-express/mobile.d.ts +23 -2
- package/dist/carriers/dhl-express/mobile.js +58 -18
- package/dist/carriers/dhl-express/status.d.ts +16 -0
- package/dist/carriers/dhl-express/status.js +38 -0
- package/dist/carriers/dhl-express/statuses.json +39 -0
- package/dist/carriers/dpd/status.d.ts +12 -2
- package/dist/carriers/dpd/status.js +30 -0
- package/dist/carriers/dpd/statuses.json +68 -0
- package/dist/carriers/dpd-de/app.d.ts +1 -6
- package/dist/carriers/dpd-de/app.js +2 -28
- package/dist/carriers/dpd-de/status.d.ts +15 -0
- package/dist/carriers/dpd-de/status.js +42 -0
- package/dist/carriers/dpd-de/statuses.json +8 -0
- package/dist/carriers/la-poste/status.d.ts +11 -1
- package/dist/carriers/la-poste/status.js +22 -6
- package/dist/carriers/la-poste/statuses.json +13 -4
- package/dist/carriers/postlogistics/status.d.ts +3 -0
- package/dist/carriers/postlogistics/status.js +5 -0
- package/dist/carriers/swiss-post/status.d.ts +7 -0
- package/dist/carriers/swiss-post/status.js +17 -0
- package/dist/carriers/swiss-post/statuses.json +34 -0
- package/dist/carriers/tnt/status.d.ts +3 -0
- package/dist/carriers/tnt/status.js +6 -0
- package/dist/carriers/tnt/statuses.json +9 -0
- package/dist/carriers/ups/status.d.ts +3 -0
- package/dist/carriers/ups/status.js +5 -0
- package/dist/carriers/yunexpress/status.d.ts +6 -0
- package/dist/carriers/yunexpress/status.js +19 -3
- package/dist/carriers/yunexpress/statuses.json +29 -0
- package/dist/core/catalog/statusMaps.d.ts +32 -0
- package/dist/core/catalog/statusMaps.js +54 -0
- package/dist/core/status/statusMap.d.ts +29 -0
- package/dist/core/status/statusMap.js +4 -0
- package/dist/places/countries.json +238 -16
- package/dist/places/hubs.json +5 -0
- package/dist/places/index.js +216 -39
- package/dist/places/names.d.mts +1 -0
- package/dist/places/names.mjs +5 -2
- package/dist/places/places.tsv.br +0 -0
- package/dist/places/trackingLocation.d.ts +2 -1
- package/dist/places/trackingLocation.js +23 -2
- package/dist/providers/seventeentrack/adapter.js +14 -1
- package/package.json +1 -1
package/NOTICE
CHANGED
|
@@ -12,4 +12,5 @@ The places gazetteer includes GeoNames data (https://www.geonames.org),
|
|
|
12
12
|
licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
|
|
13
13
|
Facility coordinates include OpenStreetMap data (https://www.openstreetmap.org/copyright),
|
|
14
14
|
licensed under the Open Database License. Natural Earth country label points
|
|
15
|
-
(https://www.naturalearthdata.com)
|
|
15
|
+
(https://www.naturalearthdata.com) and OurAirports airports
|
|
16
|
+
(https://ourairports.com/data/) are public domain.
|
package/README.md
CHANGED
|
@@ -149,7 +149,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
|
|
|
149
149
|
<!-- GENERATED:stages -->
|
|
150
150
|
<img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
|
|
151
151
|
|
|
152
|
-
The carrier folders record 2,
|
|
152
|
+
The carrier folders record 2,751 such statuses, each filed under one stage.
|
|
153
153
|
<!-- /GENERATED:stages -->
|
|
154
154
|
|
|
155
155
|
Wording nobody recorded yet goes through a classifier that reads seven European languages.
|
package/dist/app.d.ts
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Helpers shaped for the parcel app this package was extracted from: its
|
|
3
3
|
* parcel view, carrier-name hints for provider results, the clock helpers
|
|
4
|
-
* its sync uses, carrier scan-identity policies,
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* its sync uses, carrier scan-identity policies, what a carrier's status map
|
|
5
|
+
* says about a scan the app reviews, and the country a scan's location
|
|
6
|
+
* names. They change with that app and carry no stability promise; the
|
|
7
|
+
* tracking contract is the other entry points.
|
|
7
8
|
*/
|
|
8
9
|
export * from './core/catalog/parcel.js';
|
|
9
10
|
export * from './core/catalog/hints.js';
|
|
@@ -11,4 +12,6 @@ export * from './core/time/result.js';
|
|
|
11
12
|
export { sameInstantIdentityPolicy, type SameInstantIdentityPolicy, type SameInstantScan } from './core/catalog/eventIdentity.js';
|
|
12
13
|
export { universalCarrierHints } from './providers/shared/hints.js';
|
|
13
14
|
export { recognitionAskedCarriers } from './core/catalog/recognition.js';
|
|
15
|
+
export { statusMapAnswer, type ObservedStatus, type StatusMapAnswer } from './core/catalog/statusMaps.js';
|
|
16
|
+
export { normalizeStatusWording } from './core/status/statusMap.js';
|
|
14
17
|
export { countryFlag, countryName, trackingLocationCountry, trackingPlace, type TrackingPlace } from './places/trackingLocation.js';
|
package/dist/app.js
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Helpers shaped for the parcel app this package was extracted from: its
|
|
3
3
|
* parcel view, carrier-name hints for provider results, the clock helpers
|
|
4
|
-
* its sync uses, carrier scan-identity policies,
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* its sync uses, carrier scan-identity policies, what a carrier's status map
|
|
5
|
+
* says about a scan the app reviews, and the country a scan's location
|
|
6
|
+
* names. They change with that app and carry no stability promise; the
|
|
7
|
+
* tracking contract is the other entry points.
|
|
7
8
|
*/
|
|
8
9
|
export * from './core/catalog/parcel.js';
|
|
9
10
|
export * from './core/catalog/hints.js';
|
|
@@ -11,4 +12,6 @@ export * from './core/time/result.js';
|
|
|
11
12
|
export { sameInstantIdentityPolicy } from './core/catalog/eventIdentity.js';
|
|
12
13
|
export { universalCarrierHints } from './providers/shared/hints.js';
|
|
13
14
|
export { recognitionAskedCarriers } from './core/catalog/recognition.js';
|
|
15
|
+
export { statusMapAnswer } from './core/catalog/statusMaps.js';
|
|
16
|
+
export { normalizeStatusWording } from './core/status/statusMap.js';
|
|
14
17
|
export { countryFlag, countryName, trackingLocationCountry, trackingPlace } from './places/trackingLocation.js';
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import { type ClassifiedWording } from '../../core/status/index.js';
|
|
2
|
+
import { type CarrierStatusMap } from '../../core/status/statusMap.js';
|
|
2
3
|
export declare function isChronopostNotification(label: string): boolean;
|
|
3
4
|
/** The courier's drop-off scan, which can follow the pickup point's own arrival scan. */
|
|
4
5
|
export declare function isPickupDropOff(code: string, label: string): boolean;
|
|
5
6
|
/** Partner events can reuse codes; the observed wording must agree with the code. */
|
|
6
7
|
export declare function chronopostStage(code: string, label: string): ClassifiedWording;
|
|
8
|
+
/** What the map says about one scan: a code whose observed wording it carries. */
|
|
9
|
+
export declare const statusMap: CarrierStatusMap;
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { classifyWording } from '../../core/status/index.js';
|
|
2
|
+
import { normalizeStatusWording } from '../../core/status/statusMap.js';
|
|
2
3
|
const observed = new Map([
|
|
3
4
|
['DC', { label: "Colis en cours de préparation chez l'expéditeur", stage: 'registered' }],
|
|
4
5
|
['DB', { label: "Colis déposé par l'expéditeur", stage: 'accepted' }],
|
|
@@ -11,11 +12,18 @@ const observed = new Map([
|
|
|
11
12
|
['EI', { label: 'Colis entré dans le pays de destination', stage: 'in_transit' }],
|
|
12
13
|
['A2', { label: "Colis retardé à l'agence de distribution", stage: 'in_transit' }],
|
|
13
14
|
['IS', { label: 'Livraison prévue lundi prochain', stage: 'in_transit' }],
|
|
15
|
+
// The round, the courier on the way to a pickup point and its arrival there. They come
|
|
16
|
+
// within two minutes of the delivering partner's own scans, and La Poste's feed stages the
|
|
17
|
+
// same scans alike as MD1, ET1 and AG1.
|
|
18
|
+
['TA', { label: 'Colis en cours de livraison', stage: 'out_for_delivery' }],
|
|
19
|
+
['RB', { label: 'Colis en cours de livraison au point de retrait', stage: 'in_transit' }],
|
|
20
|
+
['AB', { label: 'Colis mis à disposition au point de retrait', stage: 'ready_for_pickup' }],
|
|
14
21
|
['P', { label: "Echec de livraison suite à l'absence du destinataire.", stage: 'failed_attempt' }],
|
|
15
22
|
['SK', { label: "Colis en attente d'informations complémentaires de votre part", stage: 'exception' }],
|
|
16
23
|
]);
|
|
24
|
+
const NOTIFICATION = 'Destinataire informé par SMS ou mail';
|
|
17
25
|
export function isChronopostNotification(label) {
|
|
18
|
-
return label ===
|
|
26
|
+
return label === NOTIFICATION;
|
|
19
27
|
}
|
|
20
28
|
/** The courier's drop-off scan, which can follow the pickup point's own arrival scan. */
|
|
21
29
|
export function isPickupDropOff(code, label) {
|
|
@@ -28,3 +36,14 @@ export function chronopostStage(code, label) {
|
|
|
28
36
|
return { stage: known.stage, source: 'carrier_map' };
|
|
29
37
|
return classifyWording(label, 'pending');
|
|
30
38
|
}
|
|
39
|
+
/** What the map says about one scan: a code whose observed wording it carries. */
|
|
40
|
+
export const statusMap = {
|
|
41
|
+
stage: (code, wording) => {
|
|
42
|
+
const known = code ? observed.get(code) : undefined;
|
|
43
|
+
return known && normalizeStatusWording(known.label) === wording ? known.stage : undefined;
|
|
44
|
+
},
|
|
45
|
+
gaps: [{
|
|
46
|
+
code: 'SM', wording: normalizeStatusWording(NOTIFICATION),
|
|
47
|
+
note: 'A notice to the recipient, not a scan: it keeps the stage the parcel already had.',
|
|
48
|
+
}],
|
|
49
|
+
};
|
|
@@ -139,6 +139,15 @@
|
|
|
139
139
|
"wording": "Livraison prévue lundi prochain",
|
|
140
140
|
"language": "fr"
|
|
141
141
|
},
|
|
142
|
+
{
|
|
143
|
+
"code": "TA",
|
|
144
|
+
"stage": "out_for_delivery",
|
|
145
|
+
"confirmedBy": "live",
|
|
146
|
+
"firstSeen": "2026-10-08",
|
|
147
|
+
"note": "Chronopost trackSkybillV2; code mapping requires matching wording. Seen with the delivering partner's own out-for-delivery scan, and staged like La Poste's MD1.",
|
|
148
|
+
"wording": "Colis en cours de livraison",
|
|
149
|
+
"language": "fr"
|
|
150
|
+
},
|
|
142
151
|
{
|
|
143
152
|
"code": "P",
|
|
144
153
|
"stage": "failed_attempt",
|
|
@@ -159,9 +168,18 @@
|
|
|
159
168
|
"code": "RB",
|
|
160
169
|
"stage": "in_transit",
|
|
161
170
|
"confirmedBy": "live",
|
|
162
|
-
"note": "
|
|
171
|
+
"note": "Chronopost trackSkybillV2; code mapping requires matching wording. The courier on the way to the pickup point, ahead of its arrival scan (AB); when it follows that scan, it keeps ready_for_pickup.",
|
|
163
172
|
"wording": "Colis en cours de livraison au point de retrait",
|
|
164
173
|
"language": "fr"
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
"code": "AB",
|
|
177
|
+
"stage": "ready_for_pickup",
|
|
178
|
+
"confirmedBy": "live",
|
|
179
|
+
"firstSeen": "2026-10-08",
|
|
180
|
+
"note": "Chronopost trackSkybillV2; code mapping requires matching wording. Seen with the delivering partner's own pickup-point arrival scan, and staged like La Poste's AG1.",
|
|
181
|
+
"wording": "Colis mis à disposition au point de retrait",
|
|
182
|
+
"language": "fr"
|
|
165
183
|
}
|
|
166
184
|
]
|
|
167
185
|
}
|
|
@@ -10,7 +10,7 @@ export declare function parse(payload: unknown, raw: string): CarrierResult;
|
|
|
10
10
|
export declare function parseMobile(payload: unknown, raw: string): CarrierResult;
|
|
11
11
|
export declare class DhlExpressTracker {
|
|
12
12
|
private readonly environment;
|
|
13
|
-
private readonly
|
|
13
|
+
private readonly mobile;
|
|
14
14
|
constructor(environment: AdapterEnvironment);
|
|
15
15
|
direct(number: string, context?: TrackingContext): Promise<CarrierResult>;
|
|
16
16
|
browser(number: string, context?: TrackingContext): Promise<CarrierResult>;
|
|
@@ -1,15 +1,14 @@
|
|
|
1
1
|
import { DateTime } from 'luxon';
|
|
2
|
-
import { randomUUID } from 'node:crypto';
|
|
3
2
|
import { accepted, lookupBudget, recognizeFromBrowserLookup, recognizeFromLookup } from '../../core/adapter/index.js';
|
|
4
3
|
import { isValidDhlExpressWaybill } from '../../core/detection/numericChecksums.js';
|
|
5
4
|
import { BudgetExceededError, ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
|
|
6
5
|
import { runSteps } from '../../core/runner/index.js';
|
|
7
|
-
import { classifyWording } from '../../core/status/index.js';
|
|
8
6
|
import { explicitOffsetTime, zonedTime } from '../../core/time/index.js';
|
|
9
7
|
import { clean, parseJsonBytes } from '../../core/transport/index.js';
|
|
10
8
|
import { isRecord } from '../../core/types.js';
|
|
11
9
|
import { facilityZone } from './clock.js';
|
|
12
|
-
import {
|
|
10
|
+
import { DhlMobileApi } from './mobile.js';
|
|
11
|
+
import { dhlExpressStage } from './status.js';
|
|
13
12
|
const PROVIDER = 'DHL Express';
|
|
14
13
|
const BROWSER_API = 'https://www.dhl.com/utapi';
|
|
15
14
|
const MAX_BYTES = 1_000_000;
|
|
@@ -42,22 +41,6 @@ function clock(date, time, location) {
|
|
|
42
41
|
const instant = zone ? zonedTime(wall, CLOCK_FORMAT, zone, { locale: 'en' }) : null;
|
|
43
42
|
return instant ? { time: instant.iso } : { local_time: local.toFormat("yyyy-MM-dd'T'HH:mm:ss") };
|
|
44
43
|
}
|
|
45
|
-
function stage(description) {
|
|
46
|
-
const text = description.toLowerCase();
|
|
47
|
-
if (text === 'delivered')
|
|
48
|
-
return { stage: 'delivered', source: 'carrier_map' };
|
|
49
|
-
if (text === 'shipment is out with courier for delivery')
|
|
50
|
-
return { stage: 'out_for_delivery', source: 'carrier_map' };
|
|
51
|
-
if (text.startsWith('delivery attempted'))
|
|
52
|
-
return { stage: 'failed_attempt', source: 'carrier_map' };
|
|
53
|
-
if (text === 'shipment is on hold')
|
|
54
|
-
return { stage: 'exception', source: 'carrier_map' };
|
|
55
|
-
if (text === 'shipment picked up')
|
|
56
|
-
return { stage: 'accepted', source: 'carrier_map' };
|
|
57
|
-
if (text.startsWith('clearance processing') || text.startsWith('customs clearance'))
|
|
58
|
-
return { stage: 'customs', source: 'carrier_map' };
|
|
59
|
-
return classifyWording(description, 'pending');
|
|
60
|
-
}
|
|
61
44
|
/** Public DHL web tracking: bind both the waybill and the Express division. */
|
|
62
45
|
export function parseUnified(payload, raw) {
|
|
63
46
|
const number = normalizeNumber(raw);
|
|
@@ -80,7 +63,7 @@ export function parseUnified(payload, raw) {
|
|
|
80
63
|
if (!isRecord(row) || typeof row.description !== 'string' || !row.description.trim())
|
|
81
64
|
throw new SchemaError(PROVIDER, 'DHL returned an invalid event');
|
|
82
65
|
const description = row.statusCode === 'delivered' ? 'Delivered' : clean(row.description).slice(0, 1000);
|
|
83
|
-
const mapped =
|
|
66
|
+
const mapped = dhlExpressStage(description);
|
|
84
67
|
const time = typeof row.timestamp === 'string' && /(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/i.test(row.timestamp)
|
|
85
68
|
? explicitOffsetTime(row.timestamp)?.iso : undefined;
|
|
86
69
|
const address = isRecord(row.location) && isRecord(row.location.address) ? row.location.address : {};
|
|
@@ -124,7 +107,7 @@ export function parse(payload, raw) {
|
|
|
124
107
|
if (!isRecord(row) || typeof row.description !== 'string' || !row.description.trim())
|
|
125
108
|
throw new SchemaError(PROVIDER, 'DHL Express returned an invalid checkpoint');
|
|
126
109
|
const description = clean(row.description).slice(0, 1000);
|
|
127
|
-
const mapped =
|
|
110
|
+
const mapped = dhlExpressStage(description);
|
|
128
111
|
const location = typeof row.location === 'string' ? clean(row.location).slice(0, 300) : '';
|
|
129
112
|
return { description, ...clock(row.date, row.time, location), ...(typeof row.location === 'string' ? { location } : {}),
|
|
130
113
|
stage: mapped.stage, stage_source: mapped.source };
|
|
@@ -162,14 +145,15 @@ export function parseMobile(payload, raw) {
|
|
|
162
145
|
}
|
|
163
146
|
export class DhlExpressTracker {
|
|
164
147
|
environment;
|
|
165
|
-
|
|
148
|
+
mobile;
|
|
166
149
|
constructor(environment) {
|
|
167
150
|
this.environment = environment;
|
|
151
|
+
this.mobile = new DhlMobileApi(environment);
|
|
168
152
|
}
|
|
169
153
|
async direct(number, context) {
|
|
170
154
|
const normalized = normalizeNumber(number);
|
|
171
155
|
const budget = lookupBudget(context, 10_000, PROVIDER);
|
|
172
|
-
return parseMobile(await
|
|
156
|
+
return parseMobile(await this.mobile.tracking(normalized, budget), normalized);
|
|
173
157
|
}
|
|
174
158
|
async browser(number, context) {
|
|
175
159
|
const budget = lookupBudget(context, 45_000, PROVIDER);
|
|
@@ -1,3 +1,24 @@
|
|
|
1
1
|
import type { AdapterEnvironment, LookupBudget } from '../../core/adapter/index.js';
|
|
2
|
-
/**
|
|
3
|
-
export declare
|
|
2
|
+
/** How long a confirmed plaintext-waybill setting is reused before it is read again. */
|
|
3
|
+
export declare const SETTINGS_TTL_MS: number;
|
|
4
|
+
/**
|
|
5
|
+
* The guest mobile API for one adapter instance: its device identity and the
|
|
6
|
+
* last time the application configuration allowed a plaintext waybill.
|
|
7
|
+
*/
|
|
8
|
+
export declare class DhlMobileApi {
|
|
9
|
+
private readonly environment;
|
|
10
|
+
private readonly device;
|
|
11
|
+
/** When `api_awb_encryption` last read N; null until it is read again. */
|
|
12
|
+
private settingsCheckedAt;
|
|
13
|
+
constructor(environment: AdapterEnvironment);
|
|
14
|
+
/**
|
|
15
|
+
* One waybill's shipments. The encryption setting is read first unless it was
|
|
16
|
+
* confirmed within the TTL, so an empty list counts as missing only under a
|
|
17
|
+
* recently verified configuration. Any reply other than a shipment list
|
|
18
|
+
* discards the setting. A request that got no reply, including one its own
|
|
19
|
+
* lookup cancelled or ran out of time for, says nothing about it.
|
|
20
|
+
*/
|
|
21
|
+
tracking(number: string, budget: LookupBudget): Promise<unknown>;
|
|
22
|
+
private checkSettings;
|
|
23
|
+
private request;
|
|
24
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { randomBytes, randomUUID } from 'node:crypto';
|
|
2
|
-
import { ChallengeError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
|
|
2
|
+
import { ChallengeError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
|
|
3
3
|
import { decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
|
|
4
4
|
import { isRecord } from '../../core/types.js';
|
|
5
5
|
const PROVIDER = 'DHL Express';
|
|
@@ -8,6 +8,8 @@ const VERSION = '6.1.0';
|
|
|
8
8
|
const API = `https://dhle.dhl.com/access/access/${APP}`;
|
|
9
9
|
// The shared guest application bearer is deliberately distributed with this adapter.
|
|
10
10
|
const APPLICATION_BEARER = "Bearer MtX6uKNcGM295BXaJGa83GFhTHCL9a";
|
|
11
|
+
/** How long a confirmed plaintext-waybill setting is reused before it is read again. */
|
|
12
|
+
export const SETTINGS_TTL_MS = 15 * 60_000;
|
|
11
13
|
/** Mobile errors can arrive as JSON strings or envelopes with HTTP 200. */
|
|
12
14
|
function checkReply(payload, httpStatus) {
|
|
13
15
|
const root = isRecord(payload) ? payload : {};
|
|
@@ -24,19 +26,67 @@ function checkReply(payload, httpStatus) {
|
|
|
24
26
|
if (serverError)
|
|
25
27
|
throw new UpstreamHttpError(PROVIDER, Number(serverError));
|
|
26
28
|
}
|
|
27
|
-
/**
|
|
28
|
-
|
|
29
|
-
|
|
29
|
+
/**
|
|
30
|
+
* The guest mobile API for one adapter instance: its device identity and the
|
|
31
|
+
* last time the application configuration allowed a plaintext waybill.
|
|
32
|
+
*/
|
|
33
|
+
export class DhlMobileApi {
|
|
34
|
+
environment;
|
|
35
|
+
device = randomUUID();
|
|
36
|
+
/** When `api_awb_encryption` last read N; null until it is read again. */
|
|
37
|
+
settingsCheckedAt = null;
|
|
38
|
+
constructor(environment) {
|
|
39
|
+
this.environment = environment;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* One waybill's shipments. The encryption setting is read first unless it was
|
|
43
|
+
* confirmed within the TTL, so an empty list counts as missing only under a
|
|
44
|
+
* recently verified configuration. Any reply other than a shipment list
|
|
45
|
+
* discards the setting. A request that got no reply, including one its own
|
|
46
|
+
* lookup cancelled or ran out of time for, says nothing about it.
|
|
47
|
+
*/
|
|
48
|
+
async tracking(number, budget) {
|
|
49
|
+
const checkedAt = this.settingsCheckedAt;
|
|
50
|
+
if (checkedAt === null || Date.now() - checkedAt >= SETTINGS_TTL_MS)
|
|
51
|
+
await this.checkSettings(budget);
|
|
52
|
+
let payload;
|
|
53
|
+
try {
|
|
54
|
+
payload = await this.request(budget, 'tracking', 'shipments', { airWayBill: number, countryCode: 'GB', languageCd: 'en',
|
|
55
|
+
addShipmentToODD: 'N', moreDetails: 'Y', iv: Buffer.from(randomBytes(8).toString('hex')).toString('base64'), captchaVerificationData: {} });
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
if (!(error instanceof UpstreamNetworkError) && !budget.signal.aborted)
|
|
59
|
+
this.settingsCheckedAt = null;
|
|
60
|
+
throw error;
|
|
61
|
+
}
|
|
62
|
+
if (!Array.isArray(payload))
|
|
63
|
+
this.settingsCheckedAt = null;
|
|
64
|
+
return payload;
|
|
65
|
+
}
|
|
66
|
+
async checkSettings(budget) {
|
|
67
|
+
this.settingsCheckedAt = null;
|
|
68
|
+
const checkedAt = Date.now();
|
|
69
|
+
const settings = await this.request(budget, 'countrySettingsBySettingName', 'common', { countryCode: 'GB', settingNames: ['api_awb_encryption'] });
|
|
70
|
+
if (!Array.isArray(settings) || settings.length > 20 || settings.some((setting) => !isRecord(setting)))
|
|
71
|
+
throw new SchemaError(PROVIDER, 'DHL mobile tracking returned invalid settings');
|
|
72
|
+
const encryption = settings.filter(isRecord).filter((setting) => setting.name === 'api_awb_encryption');
|
|
73
|
+
if (encryption.length !== 1 || (encryption[0].value !== 'N' && encryption[0].value !== 'Y'))
|
|
74
|
+
throw new SchemaError(PROVIDER, 'DHL mobile tracking returned invalid encryption settings');
|
|
75
|
+
if (encryption[0].value === 'Y')
|
|
76
|
+
throw new ChallengeError(PROVIDER, 'DHL mobile tracking requires waybill encryption');
|
|
77
|
+
this.settingsCheckedAt = checkedAt;
|
|
78
|
+
}
|
|
79
|
+
async request(budget, method, service, extra) {
|
|
30
80
|
budget.signal.throwIfAborted();
|
|
31
81
|
const { response, bytes } = await fetchBounded(`${API}?${new URLSearchParams({ appVersion: VERSION, service: `${service}-${method}` })}`, {
|
|
32
82
|
method: 'POST', signal: budget.signal,
|
|
33
83
|
headers: { accept: 'application/json', 'content-type': 'application/json', authorization: APPLICATION_BEARER,
|
|
34
|
-
'cache-control': 'no-cache', transactionId: randomUUID(), 'user-agent': environment.userAgent ?? 'Mozilla/5.0' },
|
|
84
|
+
'cache-control': 'no-cache', transactionId: randomUUID(), 'user-agent': this.environment.userAgent ?? 'Mozilla/5.0' },
|
|
35
85
|
body: JSON.stringify({ method, service, authentication: { provider: 'DEMP.RS1', token: '', login: '' },
|
|
36
86
|
data: { parameters: {}, timezoneOffset: '+00:00', appVersion: VERSION, UIClient: 'Android',
|
|
37
|
-
device_info: { device_unique_id: device, deviceId: device, device_language: 'en', app_id: APP,
|
|
87
|
+
device_info: { device_unique_id: this.device, deviceId: this.device, device_language: 'en', app_id: APP,
|
|
38
88
|
platform: 'Android', appStore: 'PlayStore', gpsLoc: '', pushToken: '' }, ...extra } }),
|
|
39
|
-
}, { provider: PROVIDER, timeoutMs: budget.remainingMs(), maxBytes: 1_000_000, fetcher: environment.fetcher,
|
|
89
|
+
}, { provider: PROVIDER, timeoutMs: budget.remainingMs(), maxBytes: 1_000_000, fetcher: this.environment.fetcher,
|
|
40
90
|
allowHttpStatuses: [400, 404, 410, 503] });
|
|
41
91
|
budget.signal.throwIfAborted();
|
|
42
92
|
if (response.status === 404 || response.status === 410)
|
|
@@ -59,15 +109,5 @@ export async function mobileTracking(number, budget, environment, device) {
|
|
|
59
109
|
if (response.status !== 200)
|
|
60
110
|
throw new UpstreamHttpError(PROVIDER, response.status);
|
|
61
111
|
return payload;
|
|
62
|
-
}
|
|
63
|
-
const settings = await request('countrySettingsBySettingName', 'common', { countryCode: 'GB', settingNames: ['api_awb_encryption'] });
|
|
64
|
-
if (!Array.isArray(settings) || settings.length > 20 || settings.some((setting) => !isRecord(setting)))
|
|
65
|
-
throw new SchemaError(PROVIDER, 'DHL mobile tracking returned invalid settings');
|
|
66
|
-
const encryption = settings.filter(isRecord).filter((setting) => setting.name === 'api_awb_encryption');
|
|
67
|
-
if (encryption.length !== 1 || (encryption[0].value !== 'N' && encryption[0].value !== 'Y'))
|
|
68
|
-
throw new SchemaError(PROVIDER, 'DHL mobile tracking returned invalid encryption settings');
|
|
69
|
-
if (encryption[0].value === 'Y')
|
|
70
|
-
throw new ChallengeError(PROVIDER, 'DHL mobile tracking requires waybill encryption');
|
|
71
|
-
return request('tracking', 'shipments', { airWayBill: number, countryCode: 'GB', languageCd: 'en', addShipmentToODD: 'N',
|
|
72
|
-
moreDetails: 'Y', iv: Buffer.from(randomBytes(8).toString('hex')).toString('base64'), captchaVerificationData: {} });
|
|
112
|
+
}
|
|
73
113
|
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DHL Express checkpoint wording. Both the guest mobile API and the public
|
|
3
|
+
* web tracking send DHL's English checkpoint sentences, several of which end
|
|
4
|
+
* with the facility ("Processed at PARIS - FRANCE"), so those are matched on
|
|
5
|
+
* their fixed start. Other wording goes to the shared classifier.
|
|
6
|
+
*/
|
|
7
|
+
import { type Stage } from '../../core/status/index.js';
|
|
8
|
+
import type { CarrierStatusMap } from '../../core/status/statusMap.js';
|
|
9
|
+
/** The checkpoint's stage from DHL's own wording, if the wording is one of DHL's checkpoints. */
|
|
10
|
+
export declare function dhlExpressCheckpointStage(description: string): Stage | undefined;
|
|
11
|
+
export declare function dhlExpressStage(description: string): {
|
|
12
|
+
stage: Stage;
|
|
13
|
+
source: string;
|
|
14
|
+
};
|
|
15
|
+
/** What the map says about one scan: the web feed's codes are not read, only the checkpoint wording. */
|
|
16
|
+
export declare const statusMap: CarrierStatusMap;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DHL Express checkpoint wording. Both the guest mobile API and the public
|
|
3
|
+
* web tracking send DHL's English checkpoint sentences, several of which end
|
|
4
|
+
* with the facility ("Processed at PARIS - FRANCE"), so those are matched on
|
|
5
|
+
* their fixed start. Other wording goes to the shared classifier.
|
|
6
|
+
*/
|
|
7
|
+
import { classifyWording } from '../../core/status/index.js';
|
|
8
|
+
const EXACT = new Map([
|
|
9
|
+
['shipment information received', 'registered'],
|
|
10
|
+
['shipment picked up', 'accepted'],
|
|
11
|
+
['shipment is in transit to destination', 'in_transit'],
|
|
12
|
+
['shipment is out with courier for delivery', 'out_for_delivery'],
|
|
13
|
+
['shipment is on hold', 'exception'],
|
|
14
|
+
['delivered', 'delivered'],
|
|
15
|
+
]);
|
|
16
|
+
const PREFIXES = [
|
|
17
|
+
['delivery attempted', 'failed_attempt'],
|
|
18
|
+
['clearance processing', 'customs'],
|
|
19
|
+
['customs clearance', 'customs'],
|
|
20
|
+
['processed at ', 'in_transit'],
|
|
21
|
+
['arrived at dhl sort facility', 'in_transit'],
|
|
22
|
+
['arrived at dhl delivery facility', 'in_transit'],
|
|
23
|
+
['shipment has departed from a dhl facility', 'in_transit'],
|
|
24
|
+
];
|
|
25
|
+
/** The checkpoint's stage from DHL's own wording, if the wording is one of DHL's checkpoints. */
|
|
26
|
+
export function dhlExpressCheckpointStage(description) {
|
|
27
|
+
const text = description.toLowerCase();
|
|
28
|
+
return EXACT.get(text) ?? PREFIXES.find(([start]) => text.startsWith(start))?.[1];
|
|
29
|
+
}
|
|
30
|
+
export function dhlExpressStage(description) {
|
|
31
|
+
const stage = dhlExpressCheckpointStage(description);
|
|
32
|
+
return stage ? { stage, source: 'carrier_map' } : classifyWording(description, 'pending');
|
|
33
|
+
}
|
|
34
|
+
/** What the map says about one scan: the web feed's codes are not read, only the checkpoint wording. */
|
|
35
|
+
export const statusMap = {
|
|
36
|
+
stage: (_code, wording) => dhlExpressCheckpointStage(wording),
|
|
37
|
+
gaps: [],
|
|
38
|
+
};
|
|
@@ -42,6 +42,45 @@
|
|
|
42
42
|
"stage": "in_transit",
|
|
43
43
|
"confirmedBy": "live",
|
|
44
44
|
"firstSeen": "2026-10-05"
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
"wording": "Shipment information received",
|
|
48
|
+
"language": "en",
|
|
49
|
+
"stage": "registered",
|
|
50
|
+
"confirmedBy": "live",
|
|
51
|
+
"firstSeen": "2026-10-05"
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"wording": "Processed at",
|
|
55
|
+
"language": "en",
|
|
56
|
+
"stage": "in_transit",
|
|
57
|
+
"confirmedBy": "live",
|
|
58
|
+
"firstSeen": "2026-10-05",
|
|
59
|
+
"note": "Followed by the facility, as in \"Processed at <city> - <country>\"; matched on its start."
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"wording": "Arrived at DHL Sort Facility",
|
|
63
|
+
"language": "en",
|
|
64
|
+
"stage": "in_transit",
|
|
65
|
+
"confirmedBy": "live",
|
|
66
|
+
"firstSeen": "2026-10-05",
|
|
67
|
+
"note": "Followed by the facility; matched on its start."
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"wording": "Arrived at DHL Delivery Facility",
|
|
71
|
+
"language": "en",
|
|
72
|
+
"stage": "in_transit",
|
|
73
|
+
"confirmedBy": "live",
|
|
74
|
+
"firstSeen": "2026-10-05",
|
|
75
|
+
"note": "Followed by the facility; matched on its start."
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
"wording": "Shipment has departed from a DHL facility",
|
|
79
|
+
"language": "en",
|
|
80
|
+
"stage": "in_transit",
|
|
81
|
+
"confirmedBy": "live",
|
|
82
|
+
"firstSeen": "2026-10-05",
|
|
83
|
+
"note": "Followed by the facility; matched on its start."
|
|
45
84
|
}
|
|
46
85
|
]
|
|
47
86
|
}
|
|
@@ -13,8 +13,10 @@
|
|
|
13
13
|
* `PARCEL_HANDED`, `IN_TRANSIT` and `AT_DELIVERY_CENTER` deliberately yield no
|
|
14
14
|
* stage: they move the result status to `in_transit` but leave the event
|
|
15
15
|
* unmapped so the sync's classifier records the wording for review instead of
|
|
16
|
-
* this map inventing a milestone. Scan codes are mapped
|
|
17
|
-
*
|
|
16
|
+
* this map inventing a milestone. Scan codes are mapped where a live lookup
|
|
17
|
+
* paired them with an enumeration value, or where DPD's own label names one
|
|
18
|
+
* movement inside its network (see `scanStage`). `statusMap` lists the codes
|
|
19
|
+
* and labels left unmapped on purpose.
|
|
18
20
|
*
|
|
19
21
|
* Provenance: the enumeration, the scan codes and their English labels are
|
|
20
22
|
* what the myDPD guest API returns for Swiss consignee lookups; the wording
|
|
@@ -22,6 +24,7 @@
|
|
|
22
24
|
*/
|
|
23
25
|
import type { CarrierStatus } from '../../core/result/index.js';
|
|
24
26
|
import type { Stage } from '../../core/status/index.js';
|
|
27
|
+
import type { CarrierStatusMap } from '../../core/status/statusMap.js';
|
|
25
28
|
/** English labels for the guest API enumeration, used when the API sends no translation. */
|
|
26
29
|
export declare const API_LABELS: Record<string, string>;
|
|
27
30
|
/** Wording classifier for the rendered page, which carries no status codes. */
|
|
@@ -37,3 +40,10 @@ export declare function scanStage(code: string): Stage | null;
|
|
|
37
40
|
* with no place. Paperwork, not a movement of the parcel.
|
|
38
41
|
*/
|
|
39
42
|
export declare const PROOF_OF_DELIVERY_SCAN = "DEYY";
|
|
43
|
+
/**
|
|
44
|
+
* What the map says about one scan. A scan code or an enumeration value is all
|
|
45
|
+
* it reads: the rendered page's prose has no code and gets no stage here, and
|
|
46
|
+
* a code staged by its enumeration twin depends on the reply, so it is not
|
|
47
|
+
* answered by the code alone.
|
|
48
|
+
*/
|
|
49
|
+
export declare const statusMap: CarrierStatusMap;
|
|
@@ -73,6 +73,8 @@ export function apiStage(description) {
|
|
|
73
73
|
* `parcelEvents[].eventType` scan codes. On 2026-09-26 a verified lookup
|
|
74
74
|
* listed ORI, DLI, DLO and DEY at the same wall clock as the `parcelHistory`
|
|
75
75
|
* enumeration named beside them. CCO has no twin; it ends customs clearance.
|
|
76
|
+
* HUI, HUS, DLS and DLQ are the hub and delivery-depot scans a verified
|
|
77
|
+
* domestic history lists between ORI and DLO, each labelled with one movement.
|
|
76
78
|
* ORI ("Origin depot - In") stays unmapped like its twin PARCEL_HANDED: the
|
|
77
79
|
* result stage then comes from the same wording as the scan's, and an import
|
|
78
80
|
* that cleared customs does not step back to accepted. Other codes stay
|
|
@@ -80,7 +82,11 @@ export function apiStage(description) {
|
|
|
80
82
|
*/
|
|
81
83
|
const SCAN_STAGES = {
|
|
82
84
|
CCO: 'in_transit', // "Customs - Out"
|
|
85
|
+
HUI: 'in_transit', // "Your parcel arrived at our hub"
|
|
86
|
+
HUS: 'in_transit', // "Your parcel is ready to be transported to our next premises"
|
|
83
87
|
DLI: 'in_transit', // "Destination depot - Inbound", twin AT_DELIVERY_CENTER
|
|
88
|
+
DLS: 'in_transit', // "Your parcel has been sorted and is ready for delivery"
|
|
89
|
+
DLQ: 'in_transit', // "Your parcel is at our delivery depot, it will soon be on its way"
|
|
84
90
|
DLO: 'out_for_delivery', // "Destination depot - Out for delivery", twin PARCEL_OUT_FOR_DELIVERY
|
|
85
91
|
DEY: 'delivered', // "Delivery - Delivered", twin DELIVERED
|
|
86
92
|
};
|
|
@@ -93,3 +99,27 @@ export function scanStage(code) {
|
|
|
93
99
|
* with no place. Paperwork, not a movement of the parcel.
|
|
94
100
|
*/
|
|
95
101
|
export const PROOF_OF_DELIVERY_SCAN = 'DEYY';
|
|
102
|
+
const MOVES_WITHOUT_MILESTONE = "DPD's map leaves it unmapped on purpose: it moves the parcel in transit without a milestone of its own.";
|
|
103
|
+
/**
|
|
104
|
+
* What the map says about one scan. A scan code or an enumeration value is all
|
|
105
|
+
* it reads: the rendered page's prose has no code and gets no stage here, and
|
|
106
|
+
* a code staged by its enumeration twin depends on the reply, so it is not
|
|
107
|
+
* answered by the code alone.
|
|
108
|
+
*/
|
|
109
|
+
export const statusMap = {
|
|
110
|
+
stage: (code) => (code ? scanStage(code) ?? apiStage(code) : null) ?? undefined,
|
|
111
|
+
gaps: [
|
|
112
|
+
{ code: 'PARCEL_HANDED', note: MOVES_WITHOUT_MILESTONE },
|
|
113
|
+
{ code: 'IN_TRANSIT', note: MOVES_WITHOUT_MILESTONE },
|
|
114
|
+
{ code: 'AT_DELIVERY_CENTER', note: MOVES_WITHOUT_MILESTONE },
|
|
115
|
+
{ code: 'ORI', note: "DPD's map leaves it unmapped on purpose, like its twin PARCEL_HANDED, so an import that cleared customs does not step back to accepted." },
|
|
116
|
+
{ wording: 'parcel handed to dpd', note: "The label of PARCEL_HANDED, which DPD's map leaves unmapped on purpose." },
|
|
117
|
+
{ wording: 'your parcel is on its way', note: "The label of IN_TRANSIT, which DPD's map leaves unmapped on purpose." },
|
|
118
|
+
{ wording: 'at delivery center', note: "The label of AT_DELIVERY_CENTER, which DPD's map leaves unmapped on purpose." },
|
|
119
|
+
{ code: 'SPL', note: 'Worded like IN_TRANSIT and seen on both sides of the origin depot, so it names no movement of its own.' },
|
|
120
|
+
{ code: 'OTHER', note: "The guest API's catch-all, which names no movement." },
|
|
121
|
+
{ code: 'SPE', note: 'A delivery estimate or a changed delivery day, not a scan.' },
|
|
122
|
+
{ code: 'MSDLO', note: 'The notice DPD emailed for the delivery round, not a scan.' },
|
|
123
|
+
{ code: 'MIDLI', note: "The recipient's delivery instruction, not a scan." },
|
|
124
|
+
],
|
|
125
|
+
};
|