universal-parcel-scraper 0.413.0-main.2132 → 0.414.0-main.2134

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **448 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **449 dedicated adapters** and **5 universal fallbacks**
 
 <sub>760 catalog entries · 134 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <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">
 
-The carrier folders record 14,283 such statuses, each filed under one stage.
+The carrier folders record 14,288 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/catalog.json

@@ -25350,7 +25350,8 @@
     "timezone": "Africa/Cairo",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "shipblu",
+      "recognitionRank": 789
     },
     "canaryUrl": "https://go.shipblu.com/en/",
     "trackingUrlTemplate": "https://go.shipblu.com/en/{trackingNumber}",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 760,
-  "activeAdapters": 448,
+  "activeAdapters": 449,
   "countries": 134,
   "referenceCarriers": 100,
   "comparison": {

package/dist/browser/scraper.js

@@ -19162,7 +19162,8 @@ var Re = {
 		timezone: "Africa/Cairo",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "shipblu",
+			recognitionRank: 789
 		},
 		canaryUrl: "https://go.shipblu.com/en/",
 		trackingUrlTemplate: "https://go.shipblu.com/en/{trackingNumber}",
@@ -29226,6 +29227,7 @@ var _l = {
 	seur: 870,
 	sfc: 955,
 	shadowfax: 595,
+	shipblu: 789,
 	shipentegra: 833,
 	"shree-maruti": 822,
 	"skroutz-last-mile": 913,

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

@@ -0,0 +1,15 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+/** The API the tracking page on go.shipblu.com looks the number in its address up in. */
+export declare const SHIPBLU_API = "https://api.shipblu.com/api/v1/";
+export declare class ShipbluTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/shipblu/adapter.js

@@ -0,0 +1,76 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { firstAttemptMs, networkRetryStep } from '../../core/runner/networkRetry.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { normalizeShipbluNumber, parseShipblu, PROVIDER, SHIPBLU_MAX_BYTES, shipbluOrderType } from './parser.js';
+/** The API the tracking page on go.shipblu.com looks the number in its address up in. */
+export const SHIPBLU_API = 'https://api.shipblu.com/api/v1/';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// Bot checks a CDN or firewall could put in place of the reply.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|challenge-platform|<title>\s*(?:Just a moment|Attention Required)|AwsWafIntegration|awswaf\.com/i;
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'ShipBlu answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'ShipBlu returned a reply that is not JSON', { cause });
+    }
+}
+/** The service's own answer to a number it does not know: `{"detail":"Not found."}`. */
+function unknownNumber(body) {
+    try {
+        const reply = JSON.parse(body);
+        return isRecord(reply) && typeof reply.detail === 'string' && /^not found\.?$/i.test(reply.detail.trim());
+    }
+    catch {
+        return false;
+    }
+}
+export class ShipbluTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeShipbluNumber(raw);
+        const url = `${SHIPBLU_API}${shipbluOrderType(number)}/${number}/?pin=`;
+        const read = async (signal, timeoutMs) => {
+            // The service words its errors in the language asked for; English keeps the not-found answer readable.
+            const { response, bytes } = await fetchBounded(url, { method: 'GET', signal, headers: {
+                    Accept: 'application/json', 'Accept-Language': 'en', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: SHIPBLU_MAX_BYTES, redirect: 'manual',
+                fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'ShipBlu redirected its tracking lookup');
+            const body = decodeText(bytes);
+            if (response.status === 404 && unknownNumber(body))
+                throw new NotFoundError(PROVIDER);
+            if (response.status === 404 || response.status === 410) {
+                if (CHALLENGE.test(body.slice(0, 64_000)))
+                    throw new ChallengeError(PROVIDER, 'ShipBlu answered with a browser check', { status: response.status });
+                throw new TransportError(PROVIDER, 'ShipBlu tracking lookup is unavailable', { status: response.status });
+            }
+            return parseShipblu(json(body), number);
+        };
+        // A request that fails to reach the service, or hangs, gets one more try:
+        // the first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'shipblu', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, firstAttemptMs(remainingMs)) },
+            networkRetryStep(({ signal, remainingMs }) => read(signal, remainingMs)),
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new ShipbluTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'shipblu', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeShipbluNumber(number))),
+    };
+};

package/dist/carriers/shipblu/carrier.json

@@ -17,18 +17,69 @@
   "timezone": "Africa/Cairo",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "shipblu",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 789
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "provider_code",
+    "offset_timestamps",
+    "eta",
+    "delivered_at"
+  ],
   "portal": {
     "url": "https://go.shipblu.com/en/{trackingNumber}",
     "searchUrl": "https://go.shipblu.com/en/",
     "canaryUrl": "https://go.shipblu.com/en/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "progress_rail",
+      "eta",
+      "delivered_at",
+      "failed_delivery_reason",
+      "sender_name",
+      "recipient_address",
+      "parcel_count",
+      "qr",
+      "payment_details",
+      "delivery_options"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "provider_code",
+      "offset_timestamps",
+      "eta",
+      "delivered_at",
+      "failed_delivery_reason"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "contact_details",
+      "coordinates",
+      "parcel_count",
+      "qr",
+      "payment_details",
+      "delivery_options",
+      "remarks"
+    ],
+    "unavailable": [
+      "location",
+      "weight",
+      "service_name",
+      "proof_of_delivery",
+      "destination_country",
+      "delivery_partner",
+      "delivery_tracking_number"
+    ]
   },
   "links": [
     {

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

@@ -0,0 +1,19 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "ShipBlu";
+export declare const SHIPBLU_MAX_BYTES: number;
+export type ShipbluOrderType = 'delivery-order' | 'return';
+/**
+ * The tracker's list for a number, by its leading digits as the page routes
+ * it: 1 and 31 are delivery orders, 2 and 32 returns.
+ */
+export declare function shipbluOrderType(number: string): ShipbluOrderType | undefined;
+/** A ShipBlu number for a parcel, as its digits; anything else is not one ShipBlu issues for a parcel. */
+export declare function normalizeShipbluNumber(raw: string): string;
+/**
+ * The reply of the tracking page's `GET /api/v1/{delivery-order|return}/{number}/`
+ * for one number. An unknown number is HTTP 404, which the adapter reads before
+ * this. The reply must name the number asked. It also carries the merchant, the
+ * recipient's name, phones and address and the cash to collect, which are never
+ * read.
+ */
+export declare function parseShipblu(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/shipblu/parser.js

@@ -0,0 +1,174 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { shipbluMappedStage, shipbluStage, shipbluWording } from './status.js';
+export const PROVIDER = 'ShipBlu';
+// An order with its recipient and a long history is a few kilobytes.
+export const SHIPBLU_MAX_BYTES = 256 * 1024;
+// The site's tracking box takes seven or more digits starting with 1 to 4.
+const NUMBER = /^[1-4]\d{6,39}$/;
+const CODE = /^[a-z][a-z_]{0,39}$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+// An instant as the service writes it: up to microseconds, and an offset.
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/;
+// The scans whose comment the page shows: the reason a courier gives for a missed visit.
+const ATTEMPTS = new Set(['delivery_attempted', 'return_attempted']);
+// Before pickup the page promises no day: "To be determined after picking up your order".
+const BEFORE_PICKUP = new Set(['created', 'pickup_requested', 'pickup_rescheduled']);
+// The statuses the page's timeline places on a step of their own; on any
+// other, an order on hold shows as such.
+const OWN_STEP = new Set(['created', 'pickup_requested', 'pickup_rescheduled', 'out_for_pickup', 'return_requested',
+    'picked_up', 'cancelled', 'out_for_delivery', 'out_for_return', 'delivered', 'returned']);
+const FINAL = new Set(['delivered', 'returned', 'exception']);
+// A run of eight or more digits, with spaces, brackets, dots or hyphens
+// between them, as phone numbers are written; a date stays.
+const PHONE = /(?<![A-Z\d])(?!\d{4}-\d{2}-\d{2}(?!\d))\+?\d(?:[\s().-]{0,2}\d){7,}(?![A-Z\d])/gi;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/**
+ * The tracker's list for a number, by its leading digits as the page routes
+ * it: 1 and 31 are delivery orders, 2 and 32 returns.
+ */
+export function shipbluOrderType(number) {
+    if (/^(?:1|31)/.test(number))
+        return 'delivery-order';
+    if (/^(?:2|32)/.test(number))
+        return 'return';
+    return undefined;
+}
+/** A ShipBlu number for a parcel, as its digits; anything else is not one ShipBlu issues for a parcel. */
+export function normalizeShipbluNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'ShipBlu numbers are seven or more digits starting with 1 to 4');
+    // The page looks numbers starting with 4 up as cash collections, which carry no parcel,
+    // and has no list for one starting with 3 then another digit than 1 or 2.
+    if (!shipbluOrderType(number))
+        throw new InvalidInputError(PROVIDER, 'ShipBlu tracks parcels under numbers starting with 1, 2, 31 or 32');
+    return number;
+}
+/** An instant the reply states with its offset. */
+function instant(value) {
+    return typeof value === 'string' && INSTANT.test(value.trim()) ? explicitOffsetTime(value) : null;
+}
+/** A calendar day, or nothing. */
+function day(value) {
+    if (typeof value !== 'string' || !DAY.test(value.trim()))
+        return null;
+    return DateTime.fromISO(value.trim(), { zone: 'UTC' }).isValid ? value.trim() : null;
+}
+/** A status code, in the lower case the service writes. */
+function statusCode(row) {
+    const code = typeof row.status === 'string' ? row.status.trim().toLowerCase() : '';
+    if (!CODE.test(code))
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an invalid status');
+    return code;
+}
+/** A missed visit's reason, without phone numbers. */
+function reason(row) {
+    const value = row.comment;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an invalid comment');
+    return clean(value.replace(PHONE, ''), 200).replace(/^[\s,;:.\-–]+|[\s,;:\-–]+$/g, '');
+}
+function projectRow(row) {
+    const code = statusCode(row);
+    const time = instant(row.created);
+    if (!time)
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an invalid scan time');
+    const why = ATTEMPTS.has(code) ? reason(row) : '';
+    const description = why ? `${shipbluWording(code)}: ${why}` : shipbluWording(code);
+    const staged = shipbluStage(code);
+    const event = {
+        time: time.iso,
+        description,
+        provider_code: code,
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+    return { key: JSON.stringify([time.timestamp, code, why]), scan: { event, timestamp: time.timestamp } };
+}
+/**
+ * The day the page promises: none before pickup or once the order ended, else
+ * the day the customer chose, else for a return the service's estimate. The
+ * page asks another endpoint for a delivery order's estimate, which this
+ * does not read.
+ */
+function estimate(payload, type, current, stage) {
+    if (BEFORE_PICKUP.has(current) || (stage && FINAL.has(stage)))
+        return null;
+    return day(payload.preferred_date) ?? (type === 'return' ? day(payload.estimated_date) : null);
+}
+/**
+ * The reply of the tracking page's `GET /api/v1/{delivery-order|return}/{number}/`
+ * for one number. An unknown number is HTTP 404, which the adapter reads before
+ * this. The reply must name the number asked. It also carries the merchant, the
+ * recipient's name, phones and address and the cash to collect, which are never
+ * read.
+ */
+export function parseShipblu(payload, raw) {
+    const number = normalizeShipbluNumber(raw);
+    const type = shipbluOrderType(number);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an invalid reply');
+    if (typeof payload.tracking_number !== 'string')
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an order without its number');
+    if (payload.tracking_number.trim() !== number)
+        throw new IndeterminateError(PROVIDER, 'ShipBlu answered for another order');
+    const current = statusCode(payload);
+    const rows = payload.tracking_events ?? [];
+    if (!Array.isArray(rows))
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an order with invalid scans');
+    if (rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'ShipBlu returned an oversized history');
+    const seen = new Set();
+    const scans = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'ShipBlu returned an invalid scan');
+        const { key, scan } = projectRow(row);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        scans.push(scan);
+    }
+    // Newest first; scans at the same instant keep the reverse of the order they were recorded in.
+    scans.reverse().sort((a, b) => b.timestamp - a.timestamp);
+    const events = scans.map((scan) => scan.event);
+    // The page shows an order held for the merchant on the step it waits at.
+    const onHold = payload.on_hold !== null && payload.on_hold !== undefined && !OWN_STEP.has(current);
+    const summary = onHold ? 'exception' : shipbluMappedStage(current);
+    const scanned = events.find((event) => event.stage);
+    const stage = summary ?? scanned?.stage;
+    const source = summary ? 'carrier_map' : scanned?.stage_source;
+    const delivered = stage === 'delivered'
+        ? instant(payload.delivered_date)?.iso ?? events.find((event) => event.provider_code === 'delivered')?.time : undefined;
+    const facts = {
+        expected_delivery: estimate(payload, type, current, stage),
+        ...(delivered ? { delivered_at: delivered } : {}),
+    };
+    if (!events.length) {
+        if (!summary)
+            throw new NoHistoryError(PROVIDER);
+        return {
+            status: languageStageStatus(summary), current_stage: summary, current_stage_source: 'carrier_map',
+            last_status_text: onHold ? 'On hold' : shipbluWording(current), provider_code: current,
+            last_update: delivered ?? null, ...facts, summary_only: true, events: [],
+        };
+    }
+    const newest = events[0];
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: source ?? 'carrier_map' } : {}),
+        last_status_text: onHold ? 'On hold' : newest.description,
+        last_update: newest.time,
+        ...facts,
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

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

@@ -0,0 +1,9 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage ShipBlu's map gives a status code. */
+export declare function shipbluMappedStage(code: string): Stage | undefined;
+/** The wording of a status code, as `out_for_delivery` reads "Out for delivery". */
+export declare function shipbluWording(code: string): string;
+/** A scan's stage: the map, else the shared wording rules for a code the map does not know, else nothing. */
+export declare function shipbluStage(code: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/shipblu/status.js

@@ -0,0 +1,52 @@
+import { classifyWording } from '../../core/status/index.js';
+/**
+ * ShipBlu's order statuses, as its API documentation lists them. A return
+ * order travels from the customer to the merchant, so its arrival there is
+ * `returned`, as on an order sent back.
+ */
+const CODES = new Map([
+    ['created', 'registered'],
+    ['pickup_requested', 'registered'], // The merchant asked ShipBlu to collect the order.
+    ['pickup_rescheduled', 'registered'],
+    ['out_for_pickup', 'registered'], // A courier on the way to the merchant.
+    ['return_requested', 'registered'], // The merchant asked ShipBlu to collect a return from the customer.
+    ['picked_up', 'accepted'],
+    ['in_transit', 'in_transit'], // At a ShipBlu warehouse.
+    ['en_route', 'in_transit'], // Between two warehouses.
+    ['out_for_delivery', 'out_for_delivery'],
+    ['delivery_attempted', 'failed_attempt'],
+    ['delivered', 'delivered'],
+    ['return_to_origin', 'returned'], // Refused, badly packed or out of zone: it goes back to the merchant.
+    ['out_for_return', 'returned'], // A courier taking it to the merchant.
+    ['return_postponed', 'returned'], // The merchant moved the return to the next day.
+    ['returned', 'returned'],
+    ['return_refused', 'exception'], // The merchant refused to take it back.
+    ['cancelled', 'exception'], // Cancelled by the merchant before pickup.
+]);
+/** Codes the map leaves without a stage on purpose. */
+const GAPS = new Map([
+    ['return_attempted', 'A courier could not collect a return from the customer; the parcel is not in ShipBlu\'s hands yet.'],
+]);
+/** The stage ShipBlu's map gives a status code. */
+export function shipbluMappedStage(code) {
+    return CODES.get(code);
+}
+/** The wording of a status code, as `out_for_delivery` reads "Out for delivery". */
+export function shipbluWording(code) {
+    const words = code.replace(/_+/g, ' ').trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** A scan's stage: the map, else the shared wording rules for a code the map does not know, else nothing. */
+export function shipbluStage(code) {
+    const mapped = shipbluMappedStage(code);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    if (GAPS.has(code))
+        return null;
+    const classified = classifyWording(shipbluWording(code), 'in_transit');
+    return classified.source === 'none' ? null : classified;
+}
+export const statusMap = {
+    stage: (code) => (code === null ? undefined : shipbluMappedStage(code)),
+    gaps: [...GAPS].map(([code, note]) => ({ code, note })),
+};

package/dist/carriers/shipblu/statuses.json

@@ -1,26 +1,31 @@
 {
   "carrier": "shipblu",
   "entries": [
-    {"code": "created", "wording": "Created", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"wording": "Pickup Requested", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline."},
-    {"wording": "Out for Pickup", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline. A courier is on the way to collect the order from the merchant."},
-    {"wording": "Pickup Rescheduled", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline. The pickup moved to the next business day."},
-    {"code": "picked_up", "wording": "Picked up", "stage": "accepted", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "picked_up", "wording": "تم استلام الطلب", "stage": "accepted", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "in_transit", "wording": "En Route", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "in_transit", "wording": "في مركز التوزيع", "stage": "in_transit", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"wording": "In Transit", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline. The article groups it with En Route: the order is on its way to the hub serving the customer."},
-    {"code": "out_for_delivery", "wording": "Out for Delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "out_for_delivery", "wording": "طلبك في طريقه إليك", "stage": "out_for_delivery", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "delivery_attempted", "wording": "Delivery Attempted", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline."},
-    {"code": "delivered", "wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "delivered", "wording": "تم تسليم الطلب", "stage": "delivered", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"wording": "On Hold", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline. The merchant's balance does not cover the shipping fee."},
-    {"wording": "Return to Origin", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline."},
-    {"code": "out_for_return", "wording": "Out for Return", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "out_for_return", "wording": "طلبك فى طريقه للتاجر", "stage": "returned", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history. The order is on its way back to the merchant."},
-    {"code": "returned", "wording": "Returned", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"code": "returned", "wording": "تم ارجاع الطلب", "stage": "returned", "language": "ar", "confirmedBy": "official-doc", "note": "Label in the go.shipblu.com tracker's script; not seen in a captured history."},
-    {"wording": "Canceled", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline. The order was canceled before pickup."}
+    {"code": "created", "wording": "Created", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "The merchant created the order."},
+    {"code": "pickup_requested", "wording": "Pickup requested", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "The merchant asked ShipBlu to collect the order."},
+    {"code": "out_for_pickup", "wording": "Out for pickup", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "A courier is on the way to collect the order from the merchant."},
+    {"code": "picked_up", "wording": "Picked up", "stage": "accepted", "language": "en", "confirmedBy": "live"},
+    {"code": "in_transit", "wording": "In transit", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "At a ShipBlu warehouse, as the API documentation defines the status; it alternates with en_route along the way."},
+    {"code": "en_route", "wording": "En route", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Moving from one warehouse to another, as the API documentation defines the status."},
+    {"code": "out_for_delivery", "wording": "Out for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live"},
+    {"code": "delivered", "wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "live"},
+    {"code": "pickup_rescheduled", "wording": "Pickup rescheduled", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the merchant moved the pickup."},
+    {"code": "return_requested", "wording": "Return requested", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the merchant asked ShipBlu to collect a return from the customer."},
+    {"code": "return_attempted", "wording": "Return attempted", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "Status in ShipBlu's API documentation: a courier could not collect a return from the customer, so the parcel is not in ShipBlu's hands yet."},
+    {"code": "delivery_attempted", "wording": "Delivery attempted", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation; the courier gives the reason in the scan's comment."},
+    {"code": "return_to_origin", "wording": "Return to origin", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the customer refused the order, its packaging broke ShipBlu's rules or the address is out of zone."},
+    {"code": "out_for_return", "wording": "Out for return", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: a courier is taking the order back to the merchant."},
+    {"code": "return_postponed", "wording": "Return postponed", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the merchant moved the return to the next day."},
+    {"code": "return_refused", "wording": "Return refused", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the merchant refused to take the order back."},
+    {"code": "returned", "wording": "Returned", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the order reached the merchant."},
+    {"code": "cancelled", "wording": "Cancelled", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "Status in ShipBlu's API documentation: the merchant cancelled the order before pickup."},
+    {"code": "picked_up", "wording": "تم استلام الطلب", "stage": "accepted", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline."},
+    {"code": "in_transit", "wording": "En Route", "stage": "in_transit", "language": "en", "confirmedBy": "bundle", "note": "Label of the step in the go.shipblu.com tracker's timeline."},
+    {"code": "in_transit", "wording": "في مركز التوزيع", "stage": "in_transit", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline: at the distribution centre."},
+    {"code": "out_for_delivery", "wording": "طلبك في طريقه إليك", "stage": "out_for_delivery", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline."},
+    {"code": "delivered", "wording": "تم تسليم الطلب", "stage": "delivered", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline."},
+    {"code": "out_for_return", "wording": "طلبك فى طريقه للتاجر", "stage": "returned", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline: the order is on its way back to the merchant."},
+    {"code": "returned", "wording": "تم ارجاع الطلب", "stage": "returned", "language": "ar", "confirmedBy": "bundle", "note": "Arabic label of the step in the go.shipblu.com tracker's timeline."},
+    {"wording": "On Hold", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "From ShipBlu's help article on the order timeline: the merchant's balance does not cover the shipping fee. The tracker shows it from the order's hold flag, not as a status."}
   ]
 }

package/dist/core/catalog/statusMaps.js

@@ -295,6 +295,7 @@ import { statusMap as servientrega } from '../../carriers/servientrega/status.js
 import { statusMap as sfc } from '../../carriers/sfc/status.js';
 import { statusMap as shadowfax } from '../../carriers/shadowfax/status.js';
 import { statusMap as shipa } from '../../carriers/shipa/status.js';
+import { statusMap as shipblu } from '../../carriers/shipblu/status.js';
 import { statusMap as shipentegra } from '../../carriers/shipentegra/status.js';
 import { statusMap as shreeMaruti } from '../../carriers/shree-maruti/status.js';
 import { statusMap as skroutzLastMile } from '../../carriers/skroutz-last-mile/status.js';
@@ -418,7 +419,7 @@ export const STATUS_MAPS = {
     'pts-worldwide-express': ptsWorldwideExpress, ptt, 'quantium-solutions': quantiumSolutions, 'quicksilver-sa': quicksilverSa, raben, redpack, redur, redx, relaytech,
     'rl-carriers': rlCarriers,
     'rpx-indonesia': rpxIndonesia, sagawa, saia, sailpost, sameday, 'saudi-post': saudiPost, seino, seko, sending, serpost, servientrega, sfc,
-    shadowfax, shipa, shipentegra, 'shree-maruti': shreeMaruti, 'skroutz-last-mile': skroutzLastMile, 'skynet-worldwide': skynetWorldwide,
+    shadowfax, shipa, shipblu, shipentegra, 'shree-maruti': shreeMaruti, 'skroutz-last-mile': skroutzLastMile, 'skynet-worldwide': skynetWorldwide,
     'slovak-parcel-service': slovakParcelService,
     'slovenska-posta': slovenskaPosta, 'smsa-express': smsaExpress, 'south-african-post-office': southAfricanPost,
     'southeastern-freight-lines': southeasternFreightLines, 'sp-express': spExpress, speedaf, speedex, speedx, speedy, 'spx-br': spxBr, 'spx-id': spxId, 'spx-my': spxMy,

package/dist/data/catalog.json

@@ -25350,7 +25350,8 @@
         "timezone": "Africa/Cairo",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "shipblu",
+            "recognitionRank": 789
         },
         "canaryUrl": "https://go.shipblu.com/en/",
         "trackingUrlTemplate": "https://go.shipblu.com/en/{trackingNumber}",

package/dist/generated/catalog.d.ts

@@ -16185,7 +16185,8 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Africa/Cairo";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "shipblu";
+            readonly recognitionRank: 789;
         };
         readonly canaryUrl: "https://go.shipblu.com/en/";
         readonly trackingUrlTemplate: "https://go.shipblu.com/en/{trackingNumber}";

package/dist/generated/catalog.js

@@ -25351,7 +25351,8 @@ export const CARRIER_CATALOG = {
         "timezone": "Africa/Cairo",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "shipblu",
+            "recognitionRank": 789
         },
         "canaryUrl": "https://go.shipblu.com/en/",
         "trackingUrlTemplate": "https://go.shipblu.com/en/{trackingNumber}",

package/dist/generated/recognition.js

@@ -267,6 +267,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "seur": 870,
     "sfc": 955,
     "shadowfax": 595,
+    "shipblu": 789,
     "shipentegra": 833,
     "shree-maruti": 822,
     "skroutz-last-mile": 913,

package/dist/generated/registry.js

@@ -356,6 +356,7 @@ import { adapter as sfExpress } from '../carriers/sf-express/adapter.js';
 import { adapter as sfc } from '../carriers/sfc/adapter.js';
 import { adapter as shadowfax } from '../carriers/shadowfax/adapter.js';
 import { adapter as shipa } from '../carriers/shipa/adapter.js';
+import { adapter as shipblu } from '../carriers/shipblu/adapter.js';
 import { adapter as shipentegra } from '../carriers/shipentegra/adapter.js';
 import { adapter as shreeMaruti } from '../carriers/shree-maruti/adapter.js';
 import { adapter as singaporePost } from '../carriers/singapore-post/adapter.js';
@@ -806,6 +807,7 @@ export const REGISTRY = {
         "sfc": sfc,
         "shadowfax": shadowfax,
         "shipa": shipa,
+        "shipblu": shipblu,
         "shipentegra": shipentegra,
         "shree-maruti": shreeMaruti,
         "singapore-post": singaporePost,
@@ -1507,7 +1509,7 @@ export const REGISTRY = {
         "sfc": "sfc",
         "shadowfax": "shadowfax",
         "shipa": "shipa",
-        "shipblu": "universal",
+        "shipblu": "shipblu",
         "shipentegra": "shipentegra",
         "shipup": "universal",
         "shree-anjani": "universal",

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.413.0"
+    "version": "0.414.0"
   },
   "paths": {
     "/health": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.413.0-main.2132",
+  "version": "0.414.0-main.2134",
   "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
   "type": "module",
   "license": "Apache-2.0",