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 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,133 such statuses, each filed under one stage.
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
- ['605', { stage: 'customs', status: 'in_transit' }],
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 short-lived visitor token to anyone who asks, then
10
- * accepts a batch tracking request with it. Both calls replay once after a
11
- * transport failure or an HTTP 502/503/504, and an HTTP 429 only when it
12
- * supplies a short, valid `Retry-After`.
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
- /** A fresh visitor token per lookup: it is short-lived and keyless. */
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
- /** A fresh visitor token per lookup: it is short-lived and keyless. */
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 accessToken = text(record(parseJsonBytes(bytes, 'PostNL authentication')).access_token);
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
- return accessToken;
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 accessToken = await this.visitorToken(signal);
185
- const { bytes } = await fetchBounded(TRACK_URL, {
186
- method: 'POST',
187
- headers: { ...this.headers, Authorization: `Bearer ${accessToken}` },
188
- body: JSON.stringify({ items: [trackingNumber], language_code: 'en' }),
189
- signal,
190
- }, {
191
- provider: 'PostNL tracking',
192
- timeoutMs: TRACK_TIMEOUT_MS,
193
- maxBytes: 1_000_000,
194
- retryTransient: true,
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
- fetch(trackingNumber: string, budgetMs?: number, timezone?: string | null, signal?: AbortSignal): Promise<CarrierResult>;
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, or scans Ship24 said it
328
- * has none of: the page asks the same API and shows the same answer.
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
- async fetch(trackingNumber, budgetMs, timezone = null, signal) {
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,2 @@
1
+ /** Ship24's courier code for a catalog carrier, when naming it can bring a parcel Ship24 answers 404 for. */
2
+ export declare function ship24CourierCode(carrier: string | null | undefined): string | undefined;
@@ -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
- /** The parcel as Ship24 has it stored; `to_updated` asks for a refresh. */
13
- fetch(number: string, timeoutMs: number, signal?: AbortSignal): Promise<unknown>;
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
- /** The parcel as Ship24 has it stored; `to_updated` asks for a refresh. */
82
- async fetch(number, timeoutMs, signal) {
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
- return this.#post(`${API}/${number}?lang=en`, token(number), timeoutMs, signal);
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
  }
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "Universal Parcel Scraper",
5
- "version": "0.563.0"
5
+ "version": "0.565.0"
6
6
  },
7
7
  "paths": {
8
8
  "/health": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "universal-parcel-scraper",
3
- "version": "0.563.0-main.2617",
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",