universal-parcel-scraper 0.563.0-main.2617 → 0.565.0-main.2623
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/README.md +1 -1
- package/dist/carriers/four-px/status.js +3 -2
- package/dist/carriers/four-px/statuses.json +9 -0
- package/dist/carriers/j-and-t-au/status.js +2 -0
- package/dist/carriers/j-and-t-au/statuses.json +3 -1
- package/dist/carriers/sf-express/status.js +3 -1
- package/dist/carriers/sf-express/statuses.json +35 -0
- package/dist/carriers/spring-gds/adapter.d.ts +14 -5
- package/dist/carriers/spring-gds/adapter.js +54 -16
- package/dist/carriers/yunexpress/status.js +1 -0
- package/dist/carriers/yunexpress/statuses.json +8 -0
- package/dist/providers/shared/result.js +9 -1
- package/dist/providers/ship24/adapter.d.ts +2 -1
- package/dist/providers/ship24/adapter.js +27 -9
- package/dist/providers/ship24/couriers.d.ts +2 -0
- package/dist/providers/ship24/couriers.js +41 -0
- package/dist/providers/ship24/http.d.ts +6 -2
- package/dist/providers/ship24/http.js +37 -7
- package/dist/server/openapi.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
|
|
|
155
155
|
<!-- GENERATED:stages -->
|
|
156
156
|
<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">
|
|
157
157
|
|
|
158
|
-
The carrier folders record 16,
|
|
158
|
+
The carrier folders record 16,142 such statuses, each filed under one stage.
|
|
159
159
|
<!-- /GENERATED:stages -->
|
|
160
160
|
|
|
161
161
|
Wording nobody recorded yet goes through a classifier that reads seven European languages.
|
|
@@ -30,9 +30,10 @@ const CODES = new Map([
|
|
|
30
30
|
// arrival in the destination country, so the wording decides the stage.
|
|
31
31
|
const WORDED = new Set(['FPX_O_IR', 'FPX_O_IRI']);
|
|
32
32
|
// By `normalizeStatusWording` wording. A partner's label can name its own
|
|
33
|
-
// waybill: "Waybill generated for …", as Emile words it
|
|
33
|
+
// waybill: "Waybill generated for …", as Emile words it, and its order data
|
|
34
|
+
// the partner it went to: "Order information has been transmitted to DPD."
|
|
34
35
|
const WORDING = new Map([['waybill generated', 'registered'], ['order data transmitted', 'registered']]);
|
|
35
|
-
const LABEL_FOR = /^waybill generated for [a-z0-9]
|
|
36
|
+
const LABEL_FOR = /^waybill generated for [a-z0-9]+$|^order information has been transmitted to [a-z][a-z .-]{0,30}$/;
|
|
36
37
|
// Scans a partner relays without a code, by `normalizeStatusWording` wording.
|
|
37
38
|
const UNCODED = new Map([
|
|
38
39
|
['your shipment has departed from the transit origin', 'in_transit'],
|
|
@@ -267,6 +267,15 @@
|
|
|
267
267
|
"firstSeen": "2026-10-19",
|
|
268
268
|
"note": "A partner's order-data step, relayed."
|
|
269
269
|
},
|
|
270
|
+
{
|
|
271
|
+
"code": "FPX_O_IR",
|
|
272
|
+
"wording": "Order information has been transmitted to DPD.",
|
|
273
|
+
"language": "en",
|
|
274
|
+
"stage": "registered",
|
|
275
|
+
"confirmedBy": "live",
|
|
276
|
+
"firstSeen": "2026-10-20",
|
|
277
|
+
"note": "A partner's order-data step naming the partner, relayed; other partners' names are staged the same."
|
|
278
|
+
},
|
|
270
279
|
{
|
|
271
280
|
"code": "FPX_D_DDRH",
|
|
272
281
|
"wording": "Unfortunately, consignee not present. notification was left._nabn",
|
|
@@ -17,6 +17,8 @@ const WORDINGS = new Map([
|
|
|
17
17
|
['快件到达转运中心,做发往下一站的运输准备', 'in_transit'],
|
|
18
18
|
['The parcel is dispatched from the transit center to the next destination', 'in_transit'],
|
|
19
19
|
['快件从转运中心发往下一站', 'in_transit'],
|
|
20
|
+
['Your parcel is out for delivery. If you have any questions, please call, Thank you for your patience.', 'out_for_delivery'],
|
|
21
|
+
['Your parcel has been delivered.If you have any questions,please call. We look forward to serving you again.', 'delivered'],
|
|
20
22
|
].map(([wording, stage]) => [key(wording), stage]));
|
|
21
23
|
/** The stage the map gives a scan's wording. */
|
|
22
24
|
export function jAndTAuMappedStage(wording) {
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
{"wording": "The parcel arrives at the distribution center and is prepared for transport to the next destination.", "stage": "in_transit", "language": "en", "confirmedBy": "live"},
|
|
9
9
|
{"wording": "快件到达转运中心,做发往下一站的运输准备", "stage": "in_transit", "language": "zh", "confirmedBy": "live"},
|
|
10
10
|
{"wording": "The parcel is dispatched from the transit center to the next destination", "stage": "in_transit", "language": "en", "confirmedBy": "live"},
|
|
11
|
-
{"wording": "快件从转运中心发往下一站", "stage": "in_transit", "language": "zh", "confirmedBy": "live"}
|
|
11
|
+
{"wording": "快件从转运中心发往下一站", "stage": "in_transit", "language": "zh", "confirmedBy": "live"},
|
|
12
|
+
{"wording": "Your parcel is out for delivery. If you have any questions, please call, Thank you for your patience.", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live", "note": "The tracker gives its customer service number after \"please call\", which the adapter drops."},
|
|
13
|
+
{"wording": "Your parcel has been delivered.If you have any questions,please call. We look forward to serving you again.", "stage": "delivered", "language": "en", "confirmedBy": "live", "note": "Spaced as the tracker writes it. The customer service number after \"please call\" is dropped."}
|
|
12
14
|
]
|
|
13
15
|
}
|
|
@@ -25,7 +25,9 @@ const CODES = new Map([
|
|
|
25
25
|
.map((code) => [code, TRANSIT]),
|
|
26
26
|
// In transit, on the road, on a flight or at a stopover, departed or arrived.
|
|
27
27
|
...['98', '208', '649', '310', '115', '116', '302', '305'].map((code) => [code, TRANSIT]),
|
|
28
|
-
|
|
28
|
+
// An international leg: departed from or arrived at a transit place on a flight, and waiting at one.
|
|
29
|
+
...['10', '11', '1105', '1106'].map((code) => [code, TRANSIT]),
|
|
30
|
+
...['605', '16'].map((code) => [code, { stage: 'customs', status: 'in_transit' }]),
|
|
29
31
|
]);
|
|
30
32
|
// Code 99 carries several notices: one on its way back to the sender, or one
|
|
31
33
|
// sent on to another address. Other remarks stay unclassified.
|
|
@@ -309,6 +309,41 @@
|
|
|
309
309
|
"firstSeen": "2026-10-20",
|
|
310
310
|
"note": "Official Taiwan routes opCode; the remark says the shipment is under customs clearance."
|
|
311
311
|
},
|
|
312
|
+
{
|
|
313
|
+
"code": "16",
|
|
314
|
+
"stage": "customs",
|
|
315
|
+
"confirmedBy": "live",
|
|
316
|
+
"firstSeen": "2026-10-20",
|
|
317
|
+
"note": "Official Taiwan routes opCode; the remark says the shipment is under customs clearance and asks the recipient to wait."
|
|
318
|
+
},
|
|
319
|
+
{
|
|
320
|
+
"code": "10",
|
|
321
|
+
"stage": "in_transit",
|
|
322
|
+
"confirmedBy": "live",
|
|
323
|
+
"firstSeen": "2026-10-20",
|
|
324
|
+
"note": "Official Taiwan routes opCode; the remark says the shipment departed from a transit place it names, on a flight."
|
|
325
|
+
},
|
|
326
|
+
{
|
|
327
|
+
"code": "11",
|
|
328
|
+
"stage": "in_transit",
|
|
329
|
+
"confirmedBy": "live",
|
|
330
|
+
"firstSeen": "2026-10-20",
|
|
331
|
+
"note": "Official Taiwan routes opCode; the remark says the shipment arrived at a transit place it names, off a flight."
|
|
332
|
+
},
|
|
333
|
+
{
|
|
334
|
+
"code": "1105",
|
|
335
|
+
"stage": "in_transit",
|
|
336
|
+
"confirmedBy": "live",
|
|
337
|
+
"firstSeen": "2026-10-20",
|
|
338
|
+
"note": "Official Taiwan routes opCode; the remark says the shipment is in transit at a place it names, such as an airport, and asks the recipient to wait."
|
|
339
|
+
},
|
|
340
|
+
{
|
|
341
|
+
"code": "1106",
|
|
342
|
+
"stage": "in_transit",
|
|
343
|
+
"confirmedBy": "live",
|
|
344
|
+
"firstSeen": "2026-10-20",
|
|
345
|
+
"note": "Official Taiwan routes opCode, worded like 1105 at the same places."
|
|
346
|
+
},
|
|
312
347
|
{
|
|
313
348
|
"code": "8000 / stayWhyCode 1",
|
|
314
349
|
"stage": "delivered",
|
|
@@ -6,10 +6,11 @@
|
|
|
6
6
|
* GDS is PostNL's international subsidiary and its mailingtechnology.com
|
|
7
7
|
* portal shows the same barcode (see this folder's README).
|
|
8
8
|
*
|
|
9
|
-
* `postnl.post` hands out a
|
|
10
|
-
* accepts a batch tracking request with it.
|
|
11
|
-
*
|
|
12
|
-
* supplies a short, valid
|
|
9
|
+
* `postnl.post` hands out a visitor token that lasts a day to anyone who asks,
|
|
10
|
+
* then accepts a batch tracking request with it. The tracker keeps the token
|
|
11
|
+
* for its later lookups. Both calls replay once after a transport failure or an
|
|
12
|
+
* HTTP 502/503/504, and an HTTP 429 only when it supplies a short, valid
|
|
13
|
+
* `Retry-After`.
|
|
13
14
|
*
|
|
14
15
|
* The response echoes the requested barcodes, so the item whose `item` equals
|
|
15
16
|
* the requested number is the only one read. PostNL answers an unknown barcode
|
|
@@ -23,13 +24,21 @@ export declare class PostNLTracker {
|
|
|
23
24
|
private readonly fetcher;
|
|
24
25
|
private readonly now;
|
|
25
26
|
private readonly headers;
|
|
27
|
+
/**
|
|
28
|
+
* The visitor token this tracker's lookups share until shortly before it
|
|
29
|
+
* expires. Each lasts a day, and the token endpoint's quota of 20 a minute
|
|
30
|
+
* is shared beyond one client.
|
|
31
|
+
*/
|
|
32
|
+
private cachedToken;
|
|
26
33
|
constructor(options?: {
|
|
27
34
|
fetcher?: typeof fetch;
|
|
28
35
|
now?: () => Date;
|
|
29
36
|
userAgent?: string;
|
|
30
37
|
});
|
|
31
|
-
/**
|
|
38
|
+
/** The shared visitor token, or a new one once it is close to expiring. */
|
|
32
39
|
private visitorToken;
|
|
40
|
+
/** The tracking request. A token PostNL refuses with HTTP 401 is not kept. */
|
|
41
|
+
private track;
|
|
33
42
|
fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
|
|
34
43
|
}
|
|
35
44
|
/** Kept for the host's legacy dispatch chain until it is deleted. */
|
|
@@ -11,6 +11,9 @@ const TOKEN_TIMEOUT_MS = 10_000;
|
|
|
11
11
|
const TRACK_TIMEOUT_MS = 15_000;
|
|
12
12
|
const LOOKUP_TIMEOUT_MS = 25_000;
|
|
13
13
|
const MAX_TOKEN_LENGTH = 16_384;
|
|
14
|
+
// Visitor tokens last a day (`expires_in: 86400`); one is renewed this long before it expires.
|
|
15
|
+
const MAX_TOKEN_LIFETIME_MS = 86_400_000;
|
|
16
|
+
const TOKEN_RENEWAL_MARGIN_MS = 5 * 60_000;
|
|
14
17
|
const NOT_FOUND_MESSAGE = /barcode was not found/i;
|
|
15
18
|
// PostNL's own records (the pre-advice, the shipper's data) name no country and
|
|
16
19
|
// keep Amsterdam time. See this folder's README for the evidence.
|
|
@@ -154,13 +157,23 @@ export class PostNLTracker {
|
|
|
154
157
|
fetcher;
|
|
155
158
|
now;
|
|
156
159
|
headers;
|
|
160
|
+
/**
|
|
161
|
+
* The visitor token this tracker's lookups share until shortly before it
|
|
162
|
+
* expires. Each lasts a day, and the token endpoint's quota of 20 a minute
|
|
163
|
+
* is shared beyond one client.
|
|
164
|
+
*/
|
|
165
|
+
cachedToken = null;
|
|
157
166
|
constructor(options = {}) {
|
|
158
167
|
this.fetcher = options.fetcher;
|
|
159
168
|
this.now = options.now ?? (() => new Date());
|
|
160
169
|
this.headers = siteHeaders(userAgentOf(options.userAgent));
|
|
161
170
|
}
|
|
162
|
-
/**
|
|
171
|
+
/** The shared visitor token, or a new one once it is close to expiring. */
|
|
163
172
|
async visitorToken(signal) {
|
|
173
|
+
const requestedAt = this.now().getTime();
|
|
174
|
+
if (this.cachedToken && requestedAt < this.cachedToken.expiresAt)
|
|
175
|
+
return { value: this.cachedToken.value, reused: true };
|
|
176
|
+
this.cachedToken = null;
|
|
164
177
|
const { bytes } = await fetchBounded(TOKEN_URL, { method: 'POST', headers: this.headers, body: '{}', signal }, {
|
|
165
178
|
provider: 'PostNL authentication',
|
|
166
179
|
timeoutMs: TOKEN_TIMEOUT_MS,
|
|
@@ -168,11 +181,38 @@ export class PostNLTracker {
|
|
|
168
181
|
retryTransient: true,
|
|
169
182
|
fetcher: this.fetcher,
|
|
170
183
|
});
|
|
171
|
-
const
|
|
184
|
+
const reply = record(parseJsonBytes(bytes, 'PostNL authentication'));
|
|
185
|
+
const accessToken = text(reply.access_token);
|
|
172
186
|
if (!accessToken || accessToken.length > MAX_TOKEN_LENGTH) {
|
|
173
187
|
throw new SchemaError(PROVIDER, 'PostNL returned an invalid visitor token');
|
|
174
188
|
}
|
|
175
|
-
|
|
189
|
+
// A token without a plausible lifetime serves this lookup only.
|
|
190
|
+
const lifetimeMs = typeof reply.expires_in === 'number' && Number.isFinite(reply.expires_in)
|
|
191
|
+
? Math.min(reply.expires_in * 1000, MAX_TOKEN_LIFETIME_MS) : 0;
|
|
192
|
+
if (lifetimeMs > TOKEN_RENEWAL_MARGIN_MS) {
|
|
193
|
+
this.cachedToken = { value: accessToken, expiresAt: requestedAt + lifetimeMs - TOKEN_RENEWAL_MARGIN_MS };
|
|
194
|
+
}
|
|
195
|
+
return { value: accessToken, reused: false };
|
|
196
|
+
}
|
|
197
|
+
/** The tracking request. A token PostNL refuses with HTTP 401 is not kept. */
|
|
198
|
+
async track(trackingNumber, accessToken, signal) {
|
|
199
|
+
const { bytes } = await fetchBounded(TRACK_URL, {
|
|
200
|
+
method: 'POST',
|
|
201
|
+
headers: { ...this.headers, Authorization: `Bearer ${accessToken}` },
|
|
202
|
+
body: JSON.stringify({ items: [trackingNumber], language_code: 'en' }),
|
|
203
|
+
signal,
|
|
204
|
+
}, {
|
|
205
|
+
provider: 'PostNL tracking',
|
|
206
|
+
timeoutMs: TRACK_TIMEOUT_MS,
|
|
207
|
+
maxBytes: 1_000_000,
|
|
208
|
+
retryTransient: true,
|
|
209
|
+
fetcher: this.fetcher,
|
|
210
|
+
}).catch((error) => {
|
|
211
|
+
if (error instanceof UpstreamHttpError && error.status === 401 && this.cachedToken?.value === accessToken)
|
|
212
|
+
this.cachedToken = null;
|
|
213
|
+
throw error;
|
|
214
|
+
});
|
|
215
|
+
return bytes;
|
|
176
216
|
}
|
|
177
217
|
async fetch(trackingNumber, context = {}) {
|
|
178
218
|
const budget = context.budgetMs ?? LOOKUP_TIMEOUT_MS;
|
|
@@ -181,19 +221,17 @@ export class PostNLTracker {
|
|
|
181
221
|
context.signal?.throwIfAborted();
|
|
182
222
|
const signal = AbortSignal.any([AbortSignal.timeout(Math.max(1, Math.floor(budget))), ...(context.signal ? [context.signal] : [])]);
|
|
183
223
|
try {
|
|
184
|
-
const
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
fetcher: this.fetcher,
|
|
196
|
-
});
|
|
224
|
+
const token = await this.visitorToken(signal);
|
|
225
|
+
let bytes;
|
|
226
|
+
try {
|
|
227
|
+
bytes = await this.track(trackingNumber, token.value, signal);
|
|
228
|
+
}
|
|
229
|
+
catch (error) {
|
|
230
|
+
// A shared token PostNL no longer accepts is replaced once.
|
|
231
|
+
if (!token.reused || !(error instanceof UpstreamHttpError) || error.status !== 401)
|
|
232
|
+
throw error;
|
|
233
|
+
bytes = await this.track(trackingNumber, (await this.visitorToken(signal)).value, signal);
|
|
234
|
+
}
|
|
197
235
|
signal.throwIfAborted();
|
|
198
236
|
return parsePostNLTrackingResponse(parseJsonBytes(bytes, 'PostNL tracking'), trackingNumber, this.now());
|
|
199
237
|
}
|
|
@@ -33,6 +33,7 @@ const ENTRIES = [
|
|
|
33
33
|
// delivery scan. The DHL Parcel Netherlands lines follow that carrier's codes.
|
|
34
34
|
// A partner's order pre-advice is a data record too.
|
|
35
35
|
['Sender goods issue', { status: 'pending', stage: 'registered' }],
|
|
36
|
+
['Shipping Label Created', { status: 'pending', stage: 'registered' }],
|
|
36
37
|
['POD available', { status: 'delivered', stage: 'delivered' }],
|
|
37
38
|
['Shipment not yet received or processed', { status: 'pending', stage: 'registered' }],
|
|
38
39
|
['Order information received. We\'re expecting your parcel to arrive with us.', { status: 'pending', stage: 'registered' }],
|
|
@@ -203,6 +203,14 @@
|
|
|
203
203
|
"firstSeen": "2026-10-08",
|
|
204
204
|
"note": "Relayed from DPD, placed at the delivering depot while the parcel was still in China: a data record, not a scan."
|
|
205
205
|
},
|
|
206
|
+
{
|
|
207
|
+
"wording": "Shipping Label Created",
|
|
208
|
+
"stage": "registered",
|
|
209
|
+
"language": "en",
|
|
210
|
+
"confirmedBy": "live",
|
|
211
|
+
"firstSeen": "2026-10-20",
|
|
212
|
+
"note": "The first line of a parcel for the United States, placed at a US facility: a data record, not a scan."
|
|
213
|
+
},
|
|
206
214
|
{
|
|
207
215
|
"wording": "POD available",
|
|
208
216
|
"stage": "delivered",
|
|
@@ -251,6 +251,14 @@ function providerWordingStage(description) {
|
|
|
251
251
|
return 'registered';
|
|
252
252
|
if (/^item sent[.!]?$|^item received in destination country[.!]?$/i.test(value))
|
|
253
253
|
return 'in_transit';
|
|
254
|
+
// Its office of exchange taking in an item from abroad, as ParcelsApp relays it.
|
|
255
|
+
if (/^item received at exchange office[.!]?$/i.test(value))
|
|
256
|
+
return 'in_transit';
|
|
257
|
+
// An Post's item waiting at the post office it names (code 52), and GLS Italy's delivery round, as their own maps read them.
|
|
258
|
+
if (/^your delivery is in [^,]{1,60}, post office[.!]?$/i.test(value))
|
|
259
|
+
return 'ready_for_pickup';
|
|
260
|
+
if (/^delivery scheduled during the day[.!]?$/i.test(value))
|
|
261
|
+
return 'out_for_delivery';
|
|
254
262
|
// Latvijas Pasts' acceptance at a post office, which ParcelsApp follows with the office's name.
|
|
255
263
|
if (/^item posted \/ received from customer\b/i.test(value))
|
|
256
264
|
return 'accepted';
|
|
@@ -280,7 +288,7 @@ function providerWordingStage(description) {
|
|
|
280
288
|
// A bare "parcel handed" is a hand-over to a carrier, which 17TRACK files as a pickup.
|
|
281
289
|
if (/^parcel handed[.!]?$/i.test(value))
|
|
282
290
|
return 'accepted';
|
|
283
|
-
if (/^warehouse receipt[.!]?$|^(?:package |parcel )?received by (?:the )?warehouse[.!]?$|^received in warehouse[.!]?$|^(?:package|parcel) (?:bulk )?received(?: (?:and|&) scanned)? at (?:the )?warehouse[.!]?$|^we['’]ve got it[.!]?$|^received at evri[.!]?$|^received by our network[.!]?$|^acceptance, sent to [a-z ]+$|^china post has received the mail\b|^envio recogido en origen[.!]?$|^first parcel scan along poste italiane['’]s logistic network\b|已收寄|^仓库收货$|^rfid confirmed pick-?up$|^usps in possession of item\b/i.test(value))
|
|
291
|
+
if (/^warehouse receipt[.!]?$|^(?:package |parcel )?received by (?:the )?warehouse[.!]?$|^received in warehouse[.!]?$|^(?:package|parcel) (?:bulk )?received(?: (?:and|&) scanned)? at (?:the )?warehouse[.!]?$|^we['’]ve got it[.!]?$|^received at evri[.!]?$|^received by our network[.!]?$|^acceptance, sent to [a-z ]+$|^china post has received the mail\b|^envio recogido en origen[.!]?$|^first parcel scan along poste italiane['’]s logistic network\b|已收寄|^仓库收货$|^rfid confirmed pick-?up$|^usps in possession of (?:the )?item\b/i.test(value))
|
|
284
292
|
return 'accepted';
|
|
285
293
|
if (/^goods leave the operation cent(?:er|re)[.!]?$|^the shipment has left (?:the )?origin country[.!]?$|^(?:delivery\. )?your order has been shipped from (?:\d\) )?[a-z ]{1,40} cent(?:er|re)[.!]?$|^nuevo reparto(?:\. concertacion entrega flexible)?[.!]?$|^new delivery, flexible delivery arrangement[.!]?$|^inventory in a warehouse[.!]?$|^hand over to airline[.!]?$|^in lavorazione[.!]?$|^uscita centro postale[.!]?$|^przesyłka w oddziale \w{2,20}[.!]?$|^(?:package |parcel )?(?:left|leaves?) the warehouse[.!]?$|^we['’]re processing your parcel at our hub\b|^warehouse\. (?:inbound warehouse|delivery in last mile facilities|ready to hand over to last-mile supplier)[.!]?$|^hand over to last mile[.!]?$|^at destination country\/region[.!]?$|^(?:beladung|entladung)$|^entrance to the terminal from the driver$|^outbou?n?d from pickup terminal to the line ?h[ao]u?l$|^inbound from l?ine ?h[ao]u?l to (?:the )?terminal$|^[\w ]+ warehouse, .{1,80}? processing,? (?:order has been (?:in|out)bounded|assembling operation)$|^received in site[- ]|^exported[.!]?$|^(?:the )?plane has landed[.!]?$|^received by (?:the )?airline[.!]?$|^flight delay(?:ed)?[.!](?:$| the flight scheduled\b)|^wi\s*[–-]\s*intermediate warehouse\. (?:container received|package received at intermediate warehouse)[.!]?$|^delivery branch\. received at distribution branch[.!]?$|^receiving destination mail\. received by distributor[.!]?$|^container reception[.!]?$|(?:邮件|快件)(?:到达|离开)处理中心|航空公司接收|已交承运商运输|已完成分拣|^出口海关\/放行|^启运|^干线中转/i.test(value))
|
|
286
294
|
return 'in_transit';
|
|
@@ -12,6 +12,7 @@ export interface Ship24Options extends Omit<UniversalBrowserOptions, 'signal'> {
|
|
|
12
12
|
export declare class Ship24Tracker {
|
|
13
13
|
readonly options: Ship24Options;
|
|
14
14
|
constructor(options?: Ship24Options);
|
|
15
|
-
|
|
15
|
+
/** `carrier` is the catalog id the parcel is filed under, a hint for the lookup. */
|
|
16
|
+
fetch(trackingNumber: string, budgetMs?: number, timezone?: string | null, signal?: AbortSignal, carrier?: string | null): Promise<CarrierResult>;
|
|
16
17
|
}
|
|
17
18
|
export declare const adapter: AdapterFactory;
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
import { DateTime } from 'luxon';
|
|
15
15
|
import { carrierIdFromName } from '../../core/catalog/hints.js';
|
|
16
16
|
import { carrierDefinition } from '../../core/catalog/index.js';
|
|
17
|
-
import { IndeterminateError, NoHistoryError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
|
|
17
|
+
import { IndeterminateError, NoHistoryError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
|
|
18
18
|
import { runSteps } from '../../core/runner/index.js';
|
|
19
19
|
import { scrapeUniversalPage } from '../../core/transport/browser.js';
|
|
20
20
|
import { canadaProvinceTimeZone, countryCode, countryTimeZone, EXPLICIT_OFFSET_PATTERN, firstOccurrence, regionHasTown, sharedClockZone, timeZoneCountry, usStateTimeZone, } from '../../core/time/index.js';
|
|
@@ -25,6 +25,7 @@ import { swissPostDestinationZone } from '../../carriers/swiss-post/clock.js';
|
|
|
25
25
|
import { trackingPlace } from '../../places/trackingLocation.js';
|
|
26
26
|
import { courierZone, universalCarrierHints } from '../shared/hints.js';
|
|
27
27
|
import { localEvent, numberOf, place, result } from '../shared/result.js';
|
|
28
|
+
import { ship24CourierCode } from './couriers.js';
|
|
28
29
|
import { Ship24HttpClient } from './http.js';
|
|
29
30
|
const SOURCE = 'Ship24';
|
|
30
31
|
const MAX_EVENTS = 1000;
|
|
@@ -37,6 +38,8 @@ const MAX_COURIERS = 20;
|
|
|
37
38
|
const BROWSER_RESERVE_MS = 10_000;
|
|
38
39
|
/** How long a refresh may keep a stored history waiting; most take a few seconds, a stuck carrier query 30. */
|
|
39
40
|
const REFRESH_MS = 15_000;
|
|
41
|
+
/** The least time left worth asking again with the courier named; most such answers take a second or two. */
|
|
42
|
+
const NAMED_COURIER_MIN_MS = 2_000;
|
|
40
43
|
const POSTAL_CODE = /\s*\b(?:\d{5}(?:-\d{4})?|[A-Z]\d[A-Z] ?\d[A-Z]\d)$/i;
|
|
41
44
|
/**
|
|
42
45
|
* The clock of the US state or Canadian province a location names ("NORTH
|
|
@@ -324,11 +327,12 @@ export function parseShip24Response(payload, trackingNumber, timezone = null) {
|
|
|
324
327
|
/**
|
|
325
328
|
* A browser cannot repair a rate limit or a server outage: keep the original
|
|
326
329
|
* status and Retry-After for the router's backoff instead of asking twice.
|
|
327
|
-
* Nor can it find a parcel the API answered 404 for,
|
|
328
|
-
*
|
|
330
|
+
* Nor can it find a parcel the API answered 404 for, show a courier Ship24
|
|
331
|
+
* keeps for subscribers, or find scans Ship24 said it has none of: the page
|
|
332
|
+
* asks the same API and shows the same answer.
|
|
329
333
|
*/
|
|
330
334
|
function browserCanRecover(error) {
|
|
331
|
-
return !(error instanceof NoHistoryError) && !(error instanceof UpstreamHttpError
|
|
335
|
+
return !(error instanceof NoHistoryError) && !(error instanceof NotFoundError) && !(error instanceof UpstreamHttpError
|
|
332
336
|
&& (error.status === 404 || error.status === 410 || error.status === 429 || error.status >= 500));
|
|
333
337
|
}
|
|
334
338
|
/**
|
|
@@ -336,11 +340,23 @@ function browserCanRecover(error) {
|
|
|
336
340
|
* says `to_updated`. The refresh is Ship24 querying the carriers again. If it
|
|
337
341
|
* fails or is slow, a stored history stands, as on the website; a record with
|
|
338
342
|
* no scans yet is no answer, so the refresh's failure is.
|
|
343
|
+
*
|
|
344
|
+
* Ship24 answers 404 for some couriers' parcels until the visitor names the
|
|
345
|
+
* courier, as the page's "Add details" dialog does. With the code of the
|
|
346
|
+
* carrier the parcel is filed under, a 404 is asked once more naming it. A
|
|
347
|
+
* 404 to that keeps the first; any other failure, a rate limit included, is
|
|
348
|
+
* the answer.
|
|
339
349
|
*/
|
|
340
|
-
async function currentParcel(http, number, budgetMs, signal) {
|
|
350
|
+
async function currentParcel(http, number, budgetMs, signal, courier) {
|
|
341
351
|
const deadline = performance.now() + budgetMs;
|
|
342
352
|
const left = () => Math.max(1, Math.floor(deadline - performance.now()));
|
|
343
|
-
const stored = await http.fetch(number, left(), signal)
|
|
353
|
+
const stored = await http.fetch(number, left(), signal).catch((error) => {
|
|
354
|
+
if (!courier || !(error instanceof UpstreamHttpError) || error.status !== 404 || signal?.aborted || left() < NAMED_COURIER_MIN_MS)
|
|
355
|
+
throw error;
|
|
356
|
+
return http.fetch(number, left(), signal, courier).catch((named) => {
|
|
357
|
+
throw named instanceof UpstreamHttpError && named.status === 404 ? error : named;
|
|
358
|
+
});
|
|
359
|
+
});
|
|
344
360
|
const data = isRecord(stored) && isRecord(stored.data) && stored.data.tracking_number === number ? stored.data : null;
|
|
345
361
|
if (data?.to_updated !== true || typeof data._id !== 'string')
|
|
346
362
|
return stored;
|
|
@@ -363,20 +379,22 @@ export class Ship24Tracker {
|
|
|
363
379
|
constructor(options = {}) {
|
|
364
380
|
this.options = options;
|
|
365
381
|
}
|
|
366
|
-
|
|
382
|
+
/** `carrier` is the catalog id the parcel is filed under, a hint for the lookup. */
|
|
383
|
+
async fetch(trackingNumber, budgetMs, timezone = null, signal, carrier = null) {
|
|
367
384
|
const number = numberOf(trackingNumber);
|
|
368
385
|
const timeoutMs = budgetMs ?? this.options.timeoutMs ?? 45_000;
|
|
369
386
|
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000)
|
|
370
387
|
throw new TypeError('Ship24 timeout must be between 1 and 60000 ms');
|
|
371
388
|
const http = this.options.httpClient ?? null;
|
|
372
389
|
const browser = http === null || Boolean(this.options.executablePath);
|
|
390
|
+
const courier = ship24CourierCode(carrier);
|
|
373
391
|
return runSteps({ carrier: SOURCE, budgetMs: timeoutMs, signal, recorder: this.options.recorder }, [
|
|
374
392
|
{
|
|
375
393
|
id: 'direct',
|
|
376
394
|
enabled: http !== null,
|
|
377
395
|
run: async ({ remainingMs, signal }) => ({
|
|
378
396
|
...parseShip24Response(await currentParcel(http, number, browser
|
|
379
|
-
? Math.max(remainingMs / 2, remainingMs - BROWSER_RESERVE_MS) : remainingMs, signal), number, timezone),
|
|
397
|
+
? Math.max(remainingMs / 2, remainingMs - BROWSER_RESERVE_MS) : remainingMs, signal, courier), number, timezone),
|
|
380
398
|
tracking_source: 'structured-web-response',
|
|
381
399
|
}),
|
|
382
400
|
},
|
|
@@ -406,6 +424,6 @@ export const adapter = (environment) => {
|
|
|
406
424
|
return {
|
|
407
425
|
id: SOURCE,
|
|
408
426
|
steps: ['direct', 'browser'],
|
|
409
|
-
track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.timezone ?? null, context?.signal),
|
|
427
|
+
track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.timezone ?? null, context?.signal, input.carrier ?? null),
|
|
410
428
|
};
|
|
411
429
|
};
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ship24's courier codes for catalog carriers, from its public courier list
|
|
3
|
+
* (`api.ship24.com/backoffice/api/v1/master-couriers`), with the name it
|
|
4
|
+
* shows. Listed are carriers whose numbers Ship24 answers HTTP 404 for until
|
|
5
|
+
* the visitor names the courier, as the tracking page's "Add details" dialog
|
|
6
|
+
* does, and then tracks, or says it keeps the courier for subscribers. Ask a
|
|
7
|
+
* public number of the carrier with `to_check` set to the code (see http.ts)
|
|
8
|
+
* before adding one.
|
|
9
|
+
*/
|
|
10
|
+
const COURIER_CODES = {
|
|
11
|
+
'aliexpress': 'cainiao', // Cainiao
|
|
12
|
+
'allegro-one': 'allegro', // Allegro
|
|
13
|
+
'asendia': 'asendia', // Asendia
|
|
14
|
+
'brt': 'brt-it', // BRT Italy (DPD Group)
|
|
15
|
+
'ciblex': 'ciblex', // Ciblex Express
|
|
16
|
+
'colis-prive': 'colis-prive', // Colis Prive
|
|
17
|
+
'ctt-express': 'tourline-express', // CTT Express (Tourline Express)
|
|
18
|
+
'delhivery': 'delhivery', // Delhivery
|
|
19
|
+
'dhl-ecommerce': 'dhl-global-mail', // DHL eCommerce Global
|
|
20
|
+
'dhl-ecommerce-pl': 'dhl-pl', // DHL Poland
|
|
21
|
+
'dpd-pl': 'dpd-pl', // DPD Poland
|
|
22
|
+
'dpd-ro': 'dpd-ro', // DPD Romania
|
|
23
|
+
'four-px': '4px', // 4PX
|
|
24
|
+
'globalpost': 'global-post', // Global Post
|
|
25
|
+
'imile': 'imile', // iMile
|
|
26
|
+
'mailamericas': 'mailamericas', // MailAmericas
|
|
27
|
+
'mainfreight': 'mainfreight', // Mainfreight
|
|
28
|
+
'mondial-relay': 'mondialrelay', // Mondial Relay
|
|
29
|
+
'nova-poshta': 'nova-poshta', // Nova Poshta
|
|
30
|
+
'packeta': 'packeta', // Packeta
|
|
31
|
+
'ppl': 'ppl-cz', // PPL CZ (Professional Parcel Logistic)
|
|
32
|
+
'royal-mail': 'gb-post', // Royal Mail: for subscribers only
|
|
33
|
+
'sf-express': 'sf-express', // SF Express (Shunfeng): for subscribers only
|
|
34
|
+
'shiprocket': 'shiprocket', // Shiprocket
|
|
35
|
+
'tnt': 'tnt', // TNT: the answer takes up to ten seconds
|
|
36
|
+
'ups': 'ups', // UPS: for subscribers only
|
|
37
|
+
};
|
|
38
|
+
/** Ship24's courier code for a catalog carrier, when naming it can bring a parcel Ship24 answers 404 for. */
|
|
39
|
+
export function ship24CourierCode(carrier) {
|
|
40
|
+
return carrier && Object.hasOwn(COURIER_CODES, carrier) ? COURIER_CODES[carrier] : undefined;
|
|
41
|
+
}
|
|
@@ -9,8 +9,12 @@ export declare class Ship24HttpClient {
|
|
|
9
9
|
#private;
|
|
10
10
|
readonly fetcher?: typeof fetch | undefined;
|
|
11
11
|
constructor(fetcher?: typeof fetch | undefined, userAgent?: string);
|
|
12
|
-
/**
|
|
13
|
-
|
|
12
|
+
/**
|
|
13
|
+
* The parcel as Ship24 has it stored; `to_updated` asks for a refresh. A
|
|
14
|
+
* courier code asks for the parcel with that courier, as the tracking page's
|
|
15
|
+
* "Add details" dialog does.
|
|
16
|
+
*/
|
|
17
|
+
fetch(number: string, timeoutMs: number, signal?: AbortSignal, courier?: string): Promise<unknown>;
|
|
14
18
|
/**
|
|
15
19
|
* The refresh the web app asks for when the stored parcel says `to_updated`:
|
|
16
20
|
* Ship24 queries the carriers again and replies with the parcel's current
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import { createHash, createHmac } from 'node:crypto';
|
|
13
13
|
import { fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
|
|
14
|
-
import { InvalidInputError } from '../../core/errors/index.js';
|
|
14
|
+
import { InvalidInputError, NotFoundError, UpstreamHttpError } from '../../core/errors/index.js';
|
|
15
|
+
import { isRecord } from '../../core/types.js';
|
|
15
16
|
const PAGE = 'https://www.ship24.com/tracking';
|
|
16
17
|
const API = 'https://api.ship24.com/api/parcels';
|
|
17
18
|
// Public website checksum configuration, not a provisioned API credential.
|
|
@@ -71,6 +72,27 @@ export function refreshToken(number, timestamp = Date.now()) {
|
|
|
71
72
|
}
|
|
72
73
|
// Ship24's parcel id, a UUID.
|
|
73
74
|
const PARCEL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
75
|
+
// A code of Ship24's public courier list ("dpd-pl", "4px").
|
|
76
|
+
const COURIER_CODE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
77
|
+
// The 404 message for a courier whose parcels Ship24 shows its subscribers only: "UPS is not available for website."
|
|
78
|
+
const SUBSCRIBER_ONLY = /^[^\n]{1,100} is not available for website\.?$/;
|
|
79
|
+
/**
|
|
80
|
+
* A 404 for a courier Ship24 shows its subscribers only, read from the reply's
|
|
81
|
+
* diagnostics. The courier's name is provider prose and stays out of the error.
|
|
82
|
+
*/
|
|
83
|
+
function subscriberOnly(error) {
|
|
84
|
+
if (!(error instanceof UpstreamHttpError) || error.status !== 404 || error.diagnostics?.body_read !== 'complete')
|
|
85
|
+
return null;
|
|
86
|
+
try {
|
|
87
|
+
const reply = JSON.parse(error.diagnostics.body_excerpt ?? '');
|
|
88
|
+
const message = isRecord(reply) ? reply.message : null;
|
|
89
|
+
return typeof message === 'string' && SUBSCRIBER_ONLY.test(message.trim())
|
|
90
|
+
? new NotFoundError('Ship24', 'Ship24 shows this courier to subscribers only', { cause: error, reason: 'subscriber_only' }) : null;
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
74
96
|
export class Ship24HttpClient {
|
|
75
97
|
fetcher;
|
|
76
98
|
#userAgent;
|
|
@@ -78,11 +100,17 @@ export class Ship24HttpClient {
|
|
|
78
100
|
this.fetcher = fetcher;
|
|
79
101
|
this.#userAgent = userAgentOf(userAgent);
|
|
80
102
|
}
|
|
81
|
-
/**
|
|
82
|
-
|
|
103
|
+
/**
|
|
104
|
+
* The parcel as Ship24 has it stored; `to_updated` asks for a refresh. A
|
|
105
|
+
* courier code asks for the parcel with that courier, as the tracking page's
|
|
106
|
+
* "Add details" dialog does.
|
|
107
|
+
*/
|
|
108
|
+
async fetch(number, timeoutMs, signal, courier) {
|
|
83
109
|
if (!/^(?=.*\d)[A-Z0-9]{4,40}$/.test(number))
|
|
84
110
|
throw new InvalidInputError('Ship24', 'Invalid Ship24 tracking number');
|
|
85
|
-
|
|
111
|
+
if (courier !== undefined && (courier.length > 60 || !COURIER_CODE.test(courier)))
|
|
112
|
+
throw new TypeError('Invalid Ship24 courier code');
|
|
113
|
+
return this.#post(`${API}/${number}?lang=en`, token(number), timeoutMs, signal, courier === undefined ? {} : { postCode: '', destinationCountryCode: '', to_check: [courier] });
|
|
86
114
|
}
|
|
87
115
|
/**
|
|
88
116
|
* The refresh the web app asks for when the stored parcel says `to_updated`:
|
|
@@ -94,7 +122,7 @@ export class Ship24HttpClient {
|
|
|
94
122
|
throw new InvalidInputError('Ship24', 'Invalid Ship24 parcel reference');
|
|
95
123
|
return this.#post(`${API}/update/${parcelId}/mainTN/${number}?lang=en`, refreshToken(number), timeoutMs, signal);
|
|
96
124
|
}
|
|
97
|
-
async #post(url, signature, timeoutMs, signal) {
|
|
125
|
+
async #post(url, signature, timeoutMs, signal, details = {}) {
|
|
98
126
|
if (!Number.isFinite(timeoutMs) || timeoutMs < 1)
|
|
99
127
|
throw new TypeError('Ship24 HTTP timeout must be positive');
|
|
100
128
|
const { bytes } = await fetchBounded(url, {
|
|
@@ -103,8 +131,10 @@ export class Ship24HttpClient {
|
|
|
103
131
|
Referer: PAGE, 'User-Agent': this.#userAgent, 'x-ship24-token': signature },
|
|
104
132
|
body: JSON.stringify({ userAgent: '', os: 'Linux', browser: 'Unknown', device: 'Unknown',
|
|
105
133
|
os_version: 'unknown', browser_version: 'unknown', deviceType: 'desktop',
|
|
106
|
-
orientation: 'landscape', uL: 'en-US' }),
|
|
107
|
-
}, { provider: 'Ship24 HTTP', fetcher: this.fetcher, timeoutMs: Math.floor(timeoutMs), maxBytes: 2_000_000 })
|
|
134
|
+
orientation: 'landscape', uL: 'en-US', ...details }),
|
|
135
|
+
}, { provider: 'Ship24 HTTP', fetcher: this.fetcher, timeoutMs: Math.floor(timeoutMs), maxBytes: 2_000_000 }).catch((error) => {
|
|
136
|
+
throw subscriberOnly(error) ?? error;
|
|
137
|
+
});
|
|
108
138
|
return parseJsonBytes(bytes, 'Ship24');
|
|
109
139
|
}
|
|
110
140
|
}
|
package/dist/server/openapi.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "universal-parcel-scraper",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.565.0-main.2623",
|
|
4
4
|
"description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|