universal-parcel-scraper 0.190.0-main.1346 → 0.191.0

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 **271 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **272 dedicated adapters** and **5 universal fallbacks**
 
 <sub>495 catalog entries · 113 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 9,873 such statuses, each filed under one stage.
+The carrier folders record 9,886 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

@@ -9295,7 +9295,9 @@
     "timezone": "Africa/Cairo",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "egypt-post",
+      "recognitionRank": 944,
+      "localClocks": true
     },
     "canaryUrl": "https://egyptpost.gov.eg/en-us/home/",
     "trackingSearchUrl": "https://egyptpost.gov.eg/en-us/home/",
@@ -9315,6 +9317,12 @@
       {
         "pattern": "^(?:ENO|EXP|RCC)\\d{8}EG$",
         "confidence": "low"
+      },
+      {
+        "pattern": "^[A-Z]{2}\\d{9}EG$",
+        "confidence": "low",
+        "checksum": "s10",
+        "preferred": true
       }
     ]
   },

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 495,
-  "activeAdapters": 271,
+  "activeAdapters": 272,
   "countries": 113,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -51503,6 +51503,7 @@
       "intl-post"
     ],
     "asked": [
+      "egypt-post",
       "chronopost"
     ]
   },
@@ -52086,6 +52087,20 @@
     "confidence": "low",
     "candidates": [
       "egypt-post"
+    ],
+    "asked": [
+      "egypt-post"
+    ]
+  },
+  {
+    "input": "ENO30052041EG",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "egypt-post"
+    ],
+    "asked": [
+      "egypt-post"
     ]
   },
   {
@@ -52669,6 +52684,9 @@
     "confidence": "low",
     "candidates": [
       "egypt-post"
+    ],
+    "asked": [
+      "egypt-post"
     ]
   },
   {
@@ -61675,6 +61693,14 @@
       "chronopost"
     ]
   },
+  {
+    "input": "RB536527177SG",
+    "carrier": "singapore-post",
+    "confidence": "high",
+    "candidates": [
+      "singapore-post"
+    ]
+  },
   {
     "input": "RB584629627SG",
     "carrier": "singapore-post",
@@ -61874,6 +61900,14 @@
       "correios-br"
     ]
   },
+  {
+    "input": "RE272304639SE",
+    "carrier": "postnord",
+    "confidence": "high",
+    "candidates": [
+      "postnord"
+    ]
+  },
   {
     "input": "RE924000013UY",
     "carrier": "intl-post",
@@ -63327,6 +63361,14 @@
       "spring-gds"
     ]
   },
+  {
+    "input": "RU860584495CN",
+    "carrier": "china-post",
+    "confidence": "high",
+    "candidates": [
+      "china-post"
+    ]
+  },
   {
     "input": "RUTD000239675UL",
     "carrier": "unknown",

package/dist/browser/scraper.js

@@ -7247,7 +7247,9 @@ var Ae = {
 		timezone: "Africa/Cairo",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "egypt-post",
+			recognitionRank: 944,
+			localClocks: !0
 		},
 		canaryUrl: "https://egyptpost.gov.eg/en-us/home/",
 		trackingSearchUrl: "https://egyptpost.gov.eg/en-us/home/",
@@ -7259,6 +7261,11 @@ var Ae = {
 		detectionRules: [{
 			pattern: "^(?:ENO|EXP|RCC)\\d{8}EG$",
 			confidence: "low"
+		}, {
+			pattern: "^[A-Z]{2}\\d{9}EG$",
+			confidence: "low",
+			checksum: "s10",
+			preferred: !0
 		}]
 	},
 	ekart: {
@@ -15721,7 +15728,7 @@ var Ae = {
 	"ecms-express": ["ecms-express-1"],
 	econt: [],
 	ecourier: ["ecourier-1"],
-	"egypt-post": ["egypt-post-1"],
+	"egypt-post": ["egypt-post-1", "egypt-post-s10"],
 	ekart: ["ekart-ecommerce"],
 	elta: ["elta-s10"],
 	emile: ["emile-1"],
@@ -20887,6 +20894,7 @@ var Dc = /* @__PURE__ */ new Map([
 	["CA", "canada-post"],
 	["CH", "swiss-post"],
 	["DE", "dhl"],
+	["EG", "egypt-post"],
 	["ES", "correos-spain"],
 	["FI", "posti"],
 	["FR", "la-poste"],
@@ -21154,6 +21162,7 @@ var nl = {
 	"early-bird": 350,
 	econt: 290,
 	ecoscooting: 655,
+	"egypt-post": 944,
 	elta: 150,
 	emile: 480,
 	"ems-vietnam": 962,

package/dist/carriers/egypt-post/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 lookup Egypt Post's tracking page and Android app make for a code, with English wording. */
+export declare const EGYPT_POST_ENDPOINT = "https://egyptpost.gov.eg/en-us/TrackTrace/GetShipmentDetails";
+export declare const EGYPT_POST_USER_AGENT = "Dart/3.9 (dart:io)";
+export declare class EgyptPostTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/egypt-post/adapter.js

@@ -0,0 +1,65 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, 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 } from '../../core/transport/index.js';
+import { EGYPT_POST_MAX_BYTES, normalizeEgyptPostNumber, parseEgyptPost, PROVIDER } from './parser.js';
+/** The lookup Egypt Post's tracking page and Android app make for a code, with English wording. */
+export const EGYPT_POST_ENDPOINT = 'https://egyptpost.gov.eg/en-us/TrackTrace/GetShipmentDetails';
+// The Android app's HTTP client, as Dart names it. The site's firewall blocks
+// or challenges other clients that are not browsers, and lets the app's through.
+export const EGYPT_POST_USER_AGENT = 'Dart/3.9 (dart:io)';
+const REDIRECTS = [301, 302, 303, 307, 308];
+const GONE = [404, 405, 410];
+// Cloudflare's block page and browser check.
+const CHALLENGE = /<title>\s*(?:Just a moment|Attention Required)|_cf_chl_opt|cf-turnstile|cf-error-details/i;
+export class EgyptPostTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeEgyptPostNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(`${EGYPT_POST_ENDPOINT}?barcode=${encodeURIComponent(number)}`, { signal, headers: {
+                    Accept: 'application/json', 'User-Agent': EGYPT_POST_USER_AGENT,
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: EGYPT_POST_MAX_BYTES, redirect: 'manual',
+                fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, ...GONE, 403] });
+            // The tracker answers an unknown code in its reply: a missing route is not a missing item.
+            if (REDIRECTS.includes(response.status) || GONE.includes(response.status)) {
+                throw new TransportError(PROVIDER, 'Egypt Post tracking lookup is unavailable', { status: response.status });
+            }
+            if (response.status === 403)
+                throw new ChallengeError(PROVIDER, 'Egypt Post refused the lookup at its firewall', { status: 403 });
+            const text = decodeText(bytes).replace(/^\uFEFF/, '').trim();
+            if (!text)
+                throw new IndeterminateError(PROVIDER, 'Egypt Post returned an empty reply');
+            let payload;
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (cause) {
+                if (CHALLENGE.test(text.slice(0, 64_000)))
+                    throw new ChallengeError(PROVIDER, 'Egypt Post answered with a browser check', { cause });
+                throw new SchemaError(PROVIDER, 'Egypt Post returned a reply that is not JSON', { cause });
+            }
+            return parseEgyptPost(payload, number);
+        };
+        // A lookup that fails to reach Egypt Post, or hangs, gets one more try:
+        // the first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'egypt-post', 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 EgyptPostTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return {
+        id: 'egypt-post', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeEgyptPostNumber(number))),
+    };
+};

package/dist/carriers/egypt-post/carrier.json

@@ -18,17 +18,47 @@
   "timezone": "Africa/Cairo",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "egypt-post",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 944
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location"
+  ],
   "portal": {
     "searchUrl": "https://egyptpost.gov.eg/en-us/home/",
     "canaryUrl": "https://egyptpost.gov.eg/en-us/home/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "progress_rail"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "progress_rail"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "service_name",
+      "delivered_at",
+      "offset_timestamps",
+      "sender_name",
+      "recipient_name",
+      "signatory"
+    ]
   },
   "links": [
     {
@@ -47,6 +77,13 @@
       "id": "egypt-post-1",
       "pattern": "^(?:ENO|EXP|RCC)\\d{8}EG$",
       "confidence": "low"
+    },
+    {
+      "id": "egypt-post-s10",
+      "pattern": "^[A-Z]{2}\\d{9}EG$",
+      "confidence": "low",
+      "preferred": true,
+      "checksum": "s10"
     }
   ]
 }

package/dist/carriers/egypt-post/numbers.json

@@ -63,6 +63,83 @@
         "confidence": "high"
       },
       "note": "A review on TrackingMore's Emirates Post page gives it for an item sent from Egypt to the UAE; the EG suffix names Egypt Post as the issuing post."
+    },
+    {
+      "number": "ENO30052041EG",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/MohamedSalamaMousa/shipment/blob/main/resources/js/trackShipment.js",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "egypt-post"
+        ]
+      },
+      "note": "A public Egypt Post tracking project uses it as the default item number of its lookup."
+    },
+    {
+      "number": "RU860584495CN",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://web.archive.org/web/20251023074401/https://www.egyptpost.org/track-details?itemReference=RU860584495CN",
+        "date": "2025-10-23",
+        "dateKind": "capture",
+        "access": "indexed_excerpt"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "china-post",
+        "confidence": "high"
+      },
+      "note": "Item from China looked up on Egypt Post's earlier tracker, as an archived address shows; the capture holds only a redirect."
+    },
+    {
+      "number": "RB536527177SG",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://web.archive.org/web/20251017125119/https://www.egyptpost.org/track-details?itemReference=RB536527177SG",
+        "date": "2025-10-17",
+        "dateKind": "capture",
+        "access": "indexed_excerpt"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "singapore-post",
+        "confidence": "high"
+      },
+      "note": "Item from Singapore looked up on Egypt Post's earlier tracker, as an archived address shows; the capture holds only a redirect."
+    },
+    {
+      "number": "RE272304639SE",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://web.archive.org/web/20250510121901/https://www.egyptpost.org/track-details?itemReference=RB597759784SG,RE272304639SE",
+        "date": "2025-05-10",
+        "dateKind": "capture",
+        "access": "indexed_excerpt"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "postnord",
+        "confidence": "high"
+      },
+      "note": "Item from Sweden looked up with another item on Egypt Post's earlier tracker, as an archived address shows; the capture holds only a redirect."
     }
   ]
 }

package/dist/carriers/egypt-post/parser.d.ts

@@ -0,0 +1,16 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Egypt Post";
+export declare const EGYPT_POST_MAX_BYTES = 64000;
+/**
+ * Egypt Post's tracker looks up its own S10 item codes and those of other
+ * posts while the item is in Egypt, and its three-letter domestic codes. An
+ * S10 code needs a valid check digit.
+ */
+export declare function normalizeEgyptPostNumber(raw: string): string;
+/**
+ * The reply of the tracker's `GetShipmentDetails` for one code. `case` 1 holds
+ * the item's five steps, each with the newest scan the item had in it, or
+ * nothing; 2 is the tracker's "no tracking data" and 3 its "incorrect number".
+ * The reply must name the whole requested code.
+ */
+export declare function parseEgyptPost(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/egypt-post/parser.js

@@ -0,0 +1,125 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { egyptPostStage } from './status.js';
+export const PROVIDER = 'Egypt Post';
+// A reply holds five short rows, under 2 kB.
+export const EGYPT_POST_MAX_BYTES = 64_000;
+// Egypt Post's domestic layout: three letters, eight digits and EG.
+const DOMESTIC = /^[A-Z]{3}\d{8}EG$/;
+// The tracker's five steps: registration, shipping, transport and processing, delivery, completion.
+const STEPS = 5;
+const DATE = /^\d{1,2} [A-Za-z]+ \d{4}$/;
+const CLOCK = /^(?:0?[1-9]|1[0-2]):[0-5]\d [AP]M$/i;
+/**
+ * Egypt Post's tracker looks up its own S10 item codes and those of other
+ * posts while the item is in Egypt, and its three-letter domestic codes. An
+ * S10 code needs a valid check digit.
+ */
+export function normalizeEgyptPostNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw).toUpperCase() : '';
+    if (DOMESTIC.test(number) || isValidS10TrackingNumber(number))
+        return number;
+    throw new InvalidInputError(PROVIDER, 'Egypt Post tracks S10 item codes and three letters, eight digits and EG');
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 160) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `Egypt Post returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+/**
+ * A step's clock, "05 March 2026" and "02:41 PM": the wall clock of the
+ * office that scanned the item, which can be abroad, with no zone.
+ */
+function stepClock(date, time) {
+    const parsed = DATE.test(date) && CLOCK.test(time)
+        ? DateTime.fromFormat(`${date} ${time.toUpperCase()}`, 'd MMMM yyyy h:mm a', { zone: 'UTC', locale: 'en-US' }) : null;
+    if (!parsed?.isValid)
+        throw new SchemaError(PROVIDER, 'Egypt Post returned an invalid scan time');
+    return parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+/** The office, its town and its country, each once: a scan abroad can name its country alone. */
+function place(step) {
+    const parts = [];
+    for (const part of [text(step, 'location'), text(step, 'city', 80), text(step, 'country', 80)]) {
+        if (part && !parts.some((kept) => kept.toLowerCase() === part.toLowerCase()))
+            parts.push(part);
+    }
+    return parts.join(', ');
+}
+function projectStep(step, index) {
+    if (!isRecord(step) || step.status !== index + 1)
+        throw new SchemaError(PROVIDER, 'Egypt Post returned an invalid tracking step');
+    const date = text(step, 'date', 40);
+    const time = text(step, 'time', 16);
+    const wording = text(step, 'itemStatus', 200);
+    const summary = text(step, 'mainStatus', 80);
+    // A step the item has not reached is empty.
+    if (!date && !time && !wording && !summary)
+        return null;
+    if (!wording && !summary)
+        throw new SchemaError(PROVIDER, 'Egypt Post returned a scan without wording');
+    const local = stepClock(date, time);
+    const description = wording || summary;
+    const location = place(step);
+    const staged = egyptPostStage(wording, summary);
+    const event = {
+        local_time: local,
+        ...(location ? { location } : {}),
+        description,
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+    return { event, step: index + 1 };
+}
+/**
+ * The reply of the tracker's `GetShipmentDetails` for one code. `case` 1 holds
+ * the item's five steps, each with the newest scan the item had in it, or
+ * nothing; 2 is the tracker's "no tracking data" and 3 its "incorrect number".
+ * The reply must name the whole requested code.
+ */
+export function parseEgyptPost(payload, raw) {
+    const number = normalizeEgyptPostNumber(raw);
+    if (!isRecord(payload) || typeof payload.success !== 'boolean')
+        throw new SchemaError(PROVIDER, 'Egypt Post returned an invalid reply');
+    if (!payload.success)
+        throw new IndeterminateError(PROVIDER, 'Egypt Post did not complete the lookup');
+    const data = payload.data;
+    if (!isRecord(data) || typeof data.barcode !== 'string')
+        throw new SchemaError(PROVIDER, 'Egypt Post returned an item without its code');
+    if (normalizeTrackingNumber(clean(data.barcode, 64)).toUpperCase() !== number) {
+        throw new SchemaError(PROVIDER, 'Egypt Post answered for a different item');
+    }
+    if (data.case === 2)
+        throw new NotFoundError(PROVIDER);
+    if (data.case === 3)
+        throw new InvalidInputError(PROVIDER, 'Egypt Post says the number is incorrect');
+    if (data.case !== 1 || !Array.isArray(data.data) || data.data.length !== STEPS) {
+        throw new SchemaError(PROVIDER, 'Egypt Post returned invalid tracking steps');
+    }
+    const scans = data.data.map(projectStep).filter((scan) => scan !== null);
+    if (!scans.length)
+        throw new NoHistoryError(PROVIDER);
+    // Newest first by wall clock; at the same minute the later step comes first.
+    scans.sort((left, right) => String(right.event.local_time).localeCompare(String(left.event.local_time)) || right.step - left.step);
+    const events = scans.map(({ event }) => event);
+    const newest = events[0];
+    const stage = newest.stage;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: newest.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: null,
+        last_update_local: newest.local_time,
+        expected_delivery: null,
+        events,
+        // Each step keeps only its newest scan, so the item's other scans are missing.
+        history_truncated: true,
+    };
+}

package/dist/carriers/egypt-post/status.d.ts

@@ -0,0 +1,20 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The tracker's scan wording in English, mapped whole. */
+export declare const EGYPT_POST_SCANS: Readonly<Record<string, Stage>>;
+/**
+ * The step summary each scan comes with. The page does not show it; it stages
+ * a scan whose own wording neither the map nor the shared rules know.
+ */
+export declare const EGYPT_POST_SUMMARIES: Readonly<Record<string, Stage>>;
+/** The stage Egypt Post's own scan wording gives a scan, if the map knows it. */
+export declare function egyptPostScanStage(wording: string): Stage | undefined;
+/** The stage a step summary gives, if the map knows it. */
+export declare function egyptPostSummaryStage(summary: string): Stage | undefined;
+/**
+ * A scan's stage from its wording, else the shared wording rules, else its
+ * step summary. A scan none of them stages stays visible for review.
+ */
+export declare function egyptPostStage(wording: string, summary: string): ClassifiedWording | null;
+/** The scans carry wording only; a scan without its own wording shows its step summary. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/egypt-post/status.js

@@ -0,0 +1,65 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/** The tracker's scan wording in English, mapped whole. */
+export const EGYPT_POST_SCANS = {
+    // A pickup the sender booked, before the item is collected.
+    'REQUEST PICKUP CREATED': 'registered',
+    'Shipment is collected from sender': 'accepted',
+    'Shipment was collected': 'accepted',
+    'Shipment is collected': 'accepted',
+    'Shipment Arrived at office': 'in_transit',
+    'Current Office Changed on Demand': 'in_transit',
+    // At the international office of exchange of Egypt or of the country abroad.
+    'Shipment Arrived at Office Of Exchange': 'in_transit',
+    'Shipment Dispatched from Inward Office Of Exchange': 'in_transit',
+    'Shipment dispatched to international transporter': 'in_transit',
+    'Shipment is Out for Delivery': 'out_for_delivery',
+    // The courier brought the item back to the office: a failed attempt, not a round still under way.
+    'Shipment Out for Delivery and Return to Office': 'failed_attempt',
+    'Shipment Delivered': 'delivered',
+};
+/**
+ * The step summary each scan comes with. The page does not show it; it stages
+ * a scan whose own wording neither the map nor the shared rules know.
+ */
+export const EGYPT_POST_SUMMARIES = {
+    'In PICKING': 'registered',
+    Collected: 'accepted',
+    'In Process': 'in_transit',
+    'In international Process': 'in_transit',
+    'Out for Delivery': 'out_for_delivery',
+    'Attempt of Delivery': 'failed_attempt',
+    Delivered: 'delivered',
+};
+const keyed = (map) => new Map(Object.entries(map).map(([wording, stage]) => [normalizeStatusWording(wording), stage]));
+const SCANS = keyed(EGYPT_POST_SCANS);
+const SUMMARIES = keyed(EGYPT_POST_SUMMARIES);
+/** The stage Egypt Post's own scan wording gives a scan, if the map knows it. */
+export function egyptPostScanStage(wording) {
+    return SCANS.get(normalizeStatusWording(wording));
+}
+/** The stage a step summary gives, if the map knows it. */
+export function egyptPostSummaryStage(summary) {
+    return SUMMARIES.get(normalizeStatusWording(summary));
+}
+/**
+ * A scan's stage from its wording, else the shared wording rules, else its
+ * step summary. A scan none of them stages stays visible for review.
+ */
+export function egyptPostStage(wording, summary) {
+    const mapped = wording ? egyptPostScanStage(wording) : undefined;
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    if (wording) {
+        const worded = classifyWording(wording, 'in_transit');
+        if (worded.source !== 'none')
+            return worded;
+    }
+    const summed = summary ? egyptPostSummaryStage(summary) : undefined;
+    return summed ? { stage: summed, source: 'carrier_map' } : null;
+}
+/** The scans carry wording only; a scan without its own wording shows its step summary. */
+export const statusMap = {
+    stage: (code, wording) => (code ? undefined : egyptPostScanStage(wording) ?? egyptPostSummaryStage(wording)),
+    gaps: [],
+};

package/dist/carriers/egypt-post/statuses.json

@@ -5,10 +5,23 @@
     {"wording": "Current Office Changed on Demand", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Seen in an archived capture of Egypt Post's tracker on egyptpost.org. The item was moved to another office on request."},
     {"wording": "Processed through Facility", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Seen in an archived capture of Egypt Post's tracker on egyptpost.org."},
     {"wording": "Shipment in transport", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Seen in an archived capture of Egypt Post's tracker on egyptpost.org."},
-    {"wording": "Collected", "stage": "accepted", "language": "en", "confirmedBy": "portal", "note": "A step of the progress rail on Egypt Post's earlier tracker, seen in an archived capture."},
-    {"wording": "In process", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "A step of the progress rail on Egypt Post's earlier tracker, seen in an archived capture."},
     {"wording": "Shipped", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "A step of the progress rail on Egypt Post's earlier tracker, seen in an archived capture."},
-    {"wording": "Out for Delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "portal", "note": "A step of the progress rail on Egypt Post's earlier tracker, seen in an archived capture."},
-    {"wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "portal", "note": "A step of the progress rail on Egypt Post's earlier tracker, seen in an archived capture."}
+    {"wording": "Out for Delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it. Seen as the progress rail step of the earlier tracker too."},
+    {"wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it. Seen as the progress rail step of the earlier tracker too."},
+    {"wording": "Shipment is collected from sender", "stage": "accepted", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply of the tracker's lookup."},
+    {"wording": "Shipment Arrived at office", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply of the tracker's lookup."},
+    {"wording": "Shipment Arrived at Office Of Exchange", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Seen in live replies, at an office of exchange abroad for an item sent from Egypt."},
+    {"wording": "Shipment Dispatched from Inward Office Of Exchange", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply, abroad for an item sent from Egypt."},
+    {"wording": "Shipment dispatched to international transporter", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply of the tracker's lookup."},
+    {"wording": "Shipment Delivered", "stage": "delivered", "language": "en", "confirmedBy": "live", "note": "Seen in live replies of the tracker's lookup."},
+    {"wording": "Collected", "stage": "accepted", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it. Seen as the progress rail step of the earlier tracker too."},
+    {"wording": "In Process", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it. Seen as the progress rail step \"In process\" of the earlier tracker too."},
+    {"wording": "In international Process", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it."},
+    {"wording": "REQUEST PICKUP CREATED", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply for a domestic item, in the registration step before collection."},
+    {"wording": "Shipment was collected", "stage": "accepted", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply for a domestic item."},
+    {"wording": "Shipment is Out for Delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live", "note": "Seen in a live reply of the tracker's lookup."},
+    {"wording": "Shipment Out for Delivery and Return to Office", "stage": "failed_attempt", "language": "en", "confirmedBy": "live", "note": "Seen in live replies under the step summary \"Attempt of Delivery\": the courier brought the item back to the office."},
+    {"wording": "In PICKING", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it."},
+    {"wording": "Attempt of Delivery", "stage": "failed_attempt", "language": "en", "confirmedBy": "live", "note": "A step summary in the tracker's live replies; the page does not show it."}
   ]
 }

package/dist/carriers/royal-mail/adapter.d.ts

@@ -4,7 +4,9 @@ import { type StepRecorder } from '../../core/telemetry/index.js';
 import { TrawlClient } from '../../core/transport/index.js';
 export { normalizeRoyalMailNumber, parseRoyalMailTrackingHtml, parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
 export interface RoyalMailTrackerOptions {
-    /** Fresh local Chromium; preferred when supplied. */
+    /** Private Playwright WebSocket service; preferred when supplied. Keep its capability URL outside logs and Git. */
+    browserWsEndpoint?: string | null;
+    /** Fresh local Chromium, used when no private browser endpoint is supplied. */
     executablePath?: string | null;
     /** An `http://` or `socks5://` proxy for the local Chromium's traffic. */
     browserProxy?: string | null;

package/dist/carriers/royal-mail/adapter.js

@@ -20,6 +20,7 @@ export class RoyalMailTracker {
     #fullHistory;
     #executablePath;
     #browserProxy;
+    #browserWsEndpoint;
     constructor(options = {}) {
         if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
             throw new TypeError('Royal Mail timeout must be positive');
@@ -32,6 +33,7 @@ export class RoyalMailTracker {
         this.#fullHistory = options.fullHistory ?? false;
         this.#executablePath = options.executablePath ?? null;
         this.#browserProxy = options.browserProxy?.trim() || null;
+        this.#browserWsEndpoint = options.browserWsEndpoint?.trim() || null;
     }
     /** The injected browser service, or one built from the configured URL. */
     #browserService() {
@@ -41,9 +43,9 @@ export class RoyalMailTracker {
     }
     async fetch(trackingNumber, context = {}) {
         const number = normalizeRoyalMailNumber(trackingNumber);
-        if (this.#executablePath) {
+        if (this.#browserWsEndpoint || this.#executablePath) {
             return runSteps({ carrier: 'royal-mail', budgetMs: context.budgetMs ?? this.timeoutMs,
-                signal: context.signal, recorder: this.#recorder }, [{ id: 'browser', run: ({ remainingMs, signal }) => fetchRoyalMailInBrowser(number, this.#executablePath, signal, Math.min(60_000, remainingMs), this.#fullHistory, this.#browserProxy) }]);
+                signal: context.signal, recorder: this.#recorder }, [{ id: 'browser', run: ({ remainingMs, signal }) => fetchRoyalMailInBrowser(number, this.#executablePath ?? '', signal, Math.min(60_000, remainingMs), this.#fullHistory, this.#browserProxy, this.#browserWsEndpoint) }]);
         }
         // The legacy service remains available through explicit tracker instances.
         const trawl = this.#browserService();
@@ -170,20 +172,21 @@ export class RoyalMailTracker {
     }
 }
 export const adapter = environment => {
+    const endpoint = environment.env.ROYAL_MAIL_BROWSER_WS_ENDPOINT?.trim() || null;
     const tracker = new RoyalMailTracker({ executablePath: environment.browserExecutablePath,
-        browserProxy: environment.env.ROYAL_MAIL_BROWSER_PROXY, recorder: environment.recorder, fullHistory: true });
+        browserWsEndpoint: endpoint, browserProxy: environment.env.ROYAL_MAIL_BROWSER_PROXY, recorder: environment.recorder, fullHistory: true });
     return {
         id: 'royal-mail', recordsSteps: true, steps: ['browser'],
         track: (input, context) => {
             normalizeRoyalMailNumber(input.number);
-            if (!environment.browserExecutablePath)
-                throw new ChallengeError('Royal Mail', 'Royal Mail requires TRACKING_CHROMIUM_PATH');
+            if (!endpoint && !environment.browserExecutablePath)
+                throw new ChallengeError('Royal Mail', 'Royal Mail requires TRACKING_CHROMIUM_PATH or ROYAL_MAIL_BROWSER_WS_ENDPOINT');
             return tracker.fetch(input.number, context);
         },
         recognizeWithBrowser: (number, context) => recognizeFromBrowserLookup(() => {
             normalizeRoyalMailNumber(number);
-            if (!environment.browserExecutablePath)
-                throw new ChallengeError('Royal Mail', 'Royal Mail requires TRACKING_CHROMIUM_PATH');
+            if (!endpoint && !environment.browserExecutablePath)
+                throw new ChallengeError('Royal Mail', 'Royal Mail requires TRACKING_CHROMIUM_PATH or ROYAL_MAIL_BROWSER_WS_ENDPOINT');
             return tracker.fetch(number, context);
         }),
     };

package/dist/carriers/royal-mail/browser-service.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserServer } from 'playwright-core';
+/** A private Playwright service. Its capability path and process environment never enter browser pages. */
+export declare function startRoyalMailBrowserService(env: Readonly<Record<string, string | undefined>>): Promise<BrowserServer>;

package/dist/carriers/royal-mail/browser-service.js

@@ -0,0 +1,19 @@
+import { loadChromium } from '../../core/transport/optional.js';
+/** A private Playwright service. Its capability path and process environment never enter browser pages. */
+export async function startRoyalMailBrowserService(env) {
+    const executablePath = env.TRACKING_CHROMIUM_PATH?.trim();
+    if (!executablePath)
+        throw new TypeError('Royal Mail browser service requires TRACKING_CHROMIUM_PATH');
+    const wsPath = env.ROYAL_MAIL_BROWSER_WS_PATH ?? '';
+    if (!/^\/[A-Za-z0-9_-]{32,128}$/.test(wsPath)) {
+        throw new TypeError('ROYAL_MAIL_BROWSER_WS_PATH must be an unguessable path of 32 to 128 URL-safe characters');
+    }
+    const rawPort = env.ROYAL_MAIL_BROWSER_PORT ?? '3001';
+    const port = /^\d{1,5}$/.test(rawPort) ? Number(rawPort) : 0;
+    if (port < 1 || port > 65535)
+        throw new TypeError('Invalid Royal Mail browser service port');
+    const chromium = await loadChromium('Royal Mail');
+    return chromium.launchServer({ executablePath, headless: true, host: '127.0.0.1', port, wsPath,
+        args: ['--disable-blink-features=AutomationControlled'], timeout: 20_000,
+        env: { PATH: env.PATH ?? '', HOME: env.HOME ?? '/tmp', LANG: 'en_US.UTF-8' } });
+}

package/dist/carriers/royal-mail/browser.d.ts

@@ -1,5 +1,6 @@
-import type { Page } from 'playwright-core';
+import type { Browser, Page } from 'playwright-core';
 import type { CarrierResult } from '../../core/result/index.js';
+export declare function royalMailBrowserUserAgent(browser: Browser, remote: boolean): Promise<string>;
 /** The destination the full-history reply adds to the summary, and nothing else from it. */
 export declare function royalMailDestination(summary: unknown): {
     summary?: {
@@ -8,4 +9,4 @@ export declare function royalMailDestination(summary: unknown): {
 };
 /** Observe the application's request; its issued session stays in the browser. */
 export declare function captureRoyalMailReply(page: Page, url: string, number: string, phase: 'summary' | 'events', signal: AbortSignal, timeoutMs: number, trigger: () => Promise<void>): Promise<Record<string, unknown>>;
-export declare function fetchRoyalMailInBrowser(number: string, executablePath: string, signal: AbortSignal, timeoutMs: number, fullHistory: boolean, proxy?: string | null): Promise<CarrierResult>;
+export declare function fetchRoyalMailInBrowser(number: string, executablePath: string, signal: AbortSignal, timeoutMs: number, fullHistory: boolean, proxy?: string | null, endpoint?: string | null): Promise<CarrierResult>;

package/dist/carriers/royal-mail/browser.js

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { carrierErrorKind, ChallengeError, IndeterminateError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
-import { withLocalBrowser } from '../../core/transport/localBrowser.js';
+import { withLocalBrowser, withRemoteBrowser } from '../../core/transport/localBrowser.js';
 import { isRecord } from '../../core/types.js';
 import { parseRoyalMailTrackingResponse, royalMailEventsApiUrl, royalMailSummaryApiUrl, royalMailTrackingUrl } from './parser.js';
 const PROVIDER = 'Royal Mail';
@@ -8,6 +8,25 @@ const ORIGIN = 'https://www.royalmail.com';
 const MAX_BYTES = 2_000_000;
 // The page keeps this frame hidden off-screen until hCaptcha wants a person to solve it.
 const CAPTCHA_CHALLENGE = 'iframe[src*="hcaptcha.com"][src*="frame=challenge"]:visible';
+export async function royalMailBrowserUserAgent(browser, remote) {
+    const major = browser.version().split('.')[0];
+    if (remote) {
+        // Use the browser's OS, rather than the calling server's platform.
+        const cdp = await browser.newBrowserCDPSession();
+        try {
+            const version = await cdp.send('Browser.getVersion');
+            if (!/^Mozilla\/5\.0 [\x20-\x7E]{20,300}$/.test(version.userAgent))
+                throw new SchemaError(PROVIDER);
+            return version.userAgent.replace(/HeadlessChrome\/[\d.]+/, `Chrome/${major}.0.0.0`);
+        }
+        finally {
+            await cdp.detach();
+        }
+    }
+    const platform = process.platform === 'darwin' ? 'Macintosh; Intel Mac OS X 10_15_7'
+        : process.platform === 'win32' ? 'Windows NT 10.0; Win64; x64' : 'X11; Linux x86_64';
+    return `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
+}
 // The consent manager parks the address of a frame it blocks in `data-ta-src`.
 const CAPTCHA_WITHHELD = 'iframe[data-hcaptcha-widget-id][data-ta-src]';
 /** The destination the full-history reply adds to the summary, and nothing else from it. */
@@ -142,15 +161,14 @@ export async function captureRoyalMailReply(page, url, number, phase, signal, ti
         deadline.removeEventListener('abort', aborted);
     }
 }
-export function fetchRoyalMailInBrowser(number, executablePath, signal, timeoutMs, fullHistory, proxy = null) {
-    return withLocalBrowser({ provider: PROVIDER, executablePath, signal, timeoutMs, proxy,
+export function fetchRoyalMailInBrowser(number, executablePath, signal, timeoutMs, fullHistory, proxy = null, endpoint = null) {
+    const withBrowser = endpoint ? withRemoteBrowser : withLocalBrowser;
+    return withBrowser({ provider: PROVIDER, executablePath, signal, timeoutMs, proxy, endpoint: endpoint ?? '',
         args: ['--disable-blink-features=AutomationControlled'] }, async ({ browser, signal: session, remainingMs }) => {
         try {
-            const platform = process.platform === 'darwin' ? 'Macintosh; Intel Mac OS X 10_15_7'
-                : process.platform === 'win32' ? 'Windows NT 10.0; Win64; x64' : 'X11; Linux x86_64';
-            const major = browser.version().split('.')[0];
+            const userAgent = await royalMailBrowserUserAgent(browser, endpoint !== null);
             const context = await browser.newContext({ locale: 'en-GB', acceptDownloads: false, serviceWorkers: 'block',
-                userAgent: `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36` });
+                userAgent });
             session.throwIfAborted();
             const page = await context.newPage();
             const timeout = () => Math.min(15_000, remainingMs());

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { InputRequiredError } from '../core/errors/index.js';
 import { createTracker, TrackingError } from '../facade/index.js';
 import { CARRIER_CATALOG } from '../generated/catalog.js';
 import { createTrackingServer } from '../server/index.js';
+import { startRoyalMailBrowserService } from '../carriers/royal-mail/browser-service.js';
 const help = `Universal Parcel Scraper
 
   parcel-scraper detect <number, link or text>
@@ -12,6 +13,7 @@ const help = `Universal Parcel Scraper
   parcel-scraper track <number> [--carrier <id>] [--postcode <value>] [--tracking-url <url>]
   parcel-scraper carriers
   parcel-scraper serve [--host <address>] [--port <port>]
+  parcel-scraper royal-mail-browser
 
 SCRAPER_PROVIDERS selects comma-separated providers; default: UPU.
 FLARESOLVERR_URL and TRACKING_CHROMIUM_PATH enable browser transports.
@@ -34,6 +36,15 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         console.log(help);
         return 0;
     }
+    if (command === 'royal-mail-browser') {
+        if (args.length)
+            throw new TypeError('Unexpected argument; configure the Royal Mail browser service through its environment');
+        const server = await startRoyalMailBrowserService(env);
+        console.error(JSON.stringify({ service: 'royal-mail-browser', state: 'ready' }));
+        for (const signal of ['SIGINT', 'SIGTERM'])
+            process.once(signal, () => { void server.close(); });
+        return 0;
+    }
     if (!['detect', 'recognize', 'track', 'carriers', 'serve'].includes(command))
         throw new TypeError('Unknown command; use --help');
     const values = {};

package/dist/core/catalog/hints.js

@@ -36,7 +36,7 @@ const CATALOG_NAMES = new Set([
 // request.
 const NATIONAL_POSTS = new Map([
     ['AR', 'correo-argentino'], ['AU', 'australia-post'], ['CA', 'canada-post'], ['CH', 'swiss-post'],
-    ['DE', 'dhl'], ['ES', 'correos-spain'], ['FI', 'posti'], ['FR', 'la-poste'],
+    ['DE', 'dhl'], ['EG', 'egypt-post'], ['ES', 'correos-spain'], ['FI', 'posti'], ['FR', 'la-poste'],
     ['GB', 'royal-mail'], ['JP', 'japan-post'], ['NL', 'spring-gds'], ['PL', 'poczta-polska'], ['PT', 'ctt'],
     ['RO', 'posta-romana'], ['SA', 'saudi-post'], ['SE', 'postnord'], ['UA', 'ukrposhta'], ['US', 'usps'],
 ]);

package/dist/core/catalog/statusMaps.js

@@ -64,6 +64,7 @@ import { statusMap as dsv } from '../../carriers/dsv/status.js';
 import { statusMap as dynalogic } from '../../carriers/dynalogic/status.js';
 import { statusMap as earlyBird } from '../../carriers/early-bird/status.js';
 import { statusMap as econt } from '../../carriers/econt/status.js';
+import { statusMap as egyptPost } from '../../carriers/egypt-post/status.js';
 import { statusMap as elta } from '../../carriers/elta/status.js';
 import { statusMap as emile } from '../../carriers/emile/status.js';
 import { statusMap as emsVietnam } from '../../carriers/ems-vietnam/status.js';
@@ -203,7 +204,7 @@ export const STATUS_MAPS = {
     couriersplease: couriersPlease, 'cyprus-post': cyprusPost,
     'dai-post': daiPost, dao, 'day-ross': dayRoss,
     dellin, deppon, 'dhl-express': dhlExpress, 'dhl-freight': dhlFreight, dhlink, dpd, 'dpd-de': dpdDe, 'dpd-fr': dpdFr, 'dpd-ie': dpdIe, 'dpd-pl': dpdPl, dsv, dynalogic,
-    'early-bird': earlyBird, econt, elta, emile, 'ems-vietnam': emsVietnam, envialia, 'epost-global': epostGlobal, estes,
+    'early-bird': earlyBird, econt, 'egypt-post': egyptPost, elta, emile, 'ems-vietnam': emsVietnam, envialia, 'epost-global': epostGlobal, estes,
     'express-one': expressOne, 'fan-courier': fanCourier,
     foxpost, gati, gdex, 'gebrueder-weiss': gebruederWeiss, geis, 'geniki-taxydromiki': geniki, 'geodis-pl': geodisPl, 'gls-es': glsEs, 'gls-it': glsIt,
     'go-express': goExpress, gofo, 'gofo-fr': gofoFr, 'gofo-it': gofoIt, gzyl, hanjin, 'hct-logistics': hctLogistics, helthjem, hepsijet, 'hrvatska-posta': hrvatskaPosta, hywl, imile,

package/dist/core/transport/localBrowser.d.ts

@@ -1,5 +1,5 @@
 /**
- * The one local Chromium a process runs. A carrier outage can send a whole
+ * The one browser session a process runs. A carrier outage can send a whole
  * batch to the browser tier, so lookups take turns instead of each spawning a
  * browser: a lookup waits for the browser inside its own deadline and fails
  * with a budget error when that deadline passes first.
@@ -24,3 +24,7 @@ export interface LocalBrowserSession {
     remainingMs: () => number;
 }
 export declare function withLocalBrowser<T>(options: LocalBrowserOptions, run: (session: LocalBrowserSession) => Promise<T>): Promise<T>;
+/** Connects to a private Playwright browser; closing the client disposes its contexts, not the service. */
+export declare function withRemoteBrowser<T>(options: Pick<LocalBrowserOptions, 'provider' | 'signal' | 'timeoutMs'> & {
+    endpoint: string;
+}, run: (session: LocalBrowserSession) => Promise<T>): Promise<T>;

package/dist/core/transport/localBrowser.js

@@ -1,4 +1,4 @@
-import { BudgetExceededError, carrierErrorKind } from '../errors/index.js';
+import { BudgetExceededError, carrierErrorKind, TransportError } from '../errors/index.js';
 import { loadChromium } from './optional.js';
 /** Covers the rounding of the timeouts handed to Playwright and the granularity of timers. */
 const DEADLINE_SLACK_MS = 5;
@@ -17,6 +17,33 @@ function proxyServer(value) {
     return `${url.protocol}//${url.host}`;
 }
 export async function withLocalBrowser(options, run) {
+    return withBrowser(options, run);
+}
+/** Connects to a private Playwright browser; closing the client disposes its contexts, not the service. */
+export async function withRemoteBrowser(options, run) {
+    let url;
+    try {
+        url = new URL(options.endpoint);
+    }
+    catch {
+        throw new TypeError('Browser endpoint must be a WebSocket URL');
+    }
+    if (!['ws:', 'wss:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.hash) {
+        throw new TypeError('Browser endpoint must be a WebSocket URL');
+    }
+    try {
+        return await withBrowser({ provider: options.provider, timeoutMs: options.timeoutMs, signal: options.signal, executablePath: '' }, run, url.href);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        if (carrierErrorKind(error))
+            throw error;
+        // Connection diagnostics can contain the endpoint's capability path.
+        throw new TransportError(options.provider, `${options.provider} browser service is unavailable`);
+    }
+}
+async function withBrowser(options, run, endpoint) {
     const { provider, timeoutMs } = options;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000) {
         throw new TypeError('Browser tracking timeout must be between 1 and 60000 ms');
@@ -69,9 +96,11 @@ export async function withLocalBrowser(options, run) {
         if (signal.aborted)
             throw stopped();
         // Do not pass the application environment (database or API secrets) to Chromium.
-        launching = chromium.launch({ executablePath: options.executablePath, headless: true, args: [...(options.args ?? [])],
-            timeout: Math.min(remainingMs(), 10_000), ...(proxy ? { proxy: { server: proxy } } : {}),
-            env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '/tmp', LANG: 'en_US.UTF-8' } });
+        // The private service binds to loopback; its Host check must survive a tunnel's different address.
+        launching = endpoint ? chromium.connect(endpoint, { timeout: Math.min(remainingMs(), 10_000), headers: { Host: 'localhost' } })
+            : chromium.launch({ executablePath: options.executablePath, headless: true, args: [...(options.args ?? [])],
+                timeout: Math.min(remainingMs(), 10_000), ...(proxy ? { proxy: { server: proxy } } : {}),
+                env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '/tmp', LANG: 'en_US.UTF-8' } });
         browser = await unlessStopped(launching);
         return await unlessStopped(run({ browser, signal, remainingMs }));
     }

package/dist/data/catalog.json

@@ -9295,7 +9295,9 @@
         "timezone": "Africa/Cairo",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "egypt-post",
+            "recognitionRank": 944,
+            "localClocks": true
         },
         "canaryUrl": "https://egyptpost.gov.eg/en-us/home/",
         "trackingSearchUrl": "https://egyptpost.gov.eg/en-us/home/",
@@ -9315,6 +9317,12 @@
             {
                 "pattern": "^(?:ENO|EXP|RCC)\\d{8}EG$",
                 "confidence": "low"
+            },
+            {
+                "pattern": "^[A-Z]{2}\\d{9}EG$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
             }
         ]
     },

package/dist/generated/catalog.d.ts

@@ -6057,7 +6057,9 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Africa/Cairo";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "egypt-post";
+            readonly recognitionRank: 944;
+            readonly localClocks: true;
         };
         readonly canaryUrl: "https://egyptpost.gov.eg/en-us/home/";
         readonly trackingSearchUrl: "https://egyptpost.gov.eg/en-us/home/";
@@ -6069,6 +6071,11 @@ export declare const CARRIER_CATALOG: {
         readonly detectionRules: readonly [{
             readonly pattern: "^(?:ENO|EXP|RCC)\\d{8}EG$";
             readonly confidence: "low";
+        }, {
+            readonly pattern: "^[A-Z]{2}\\d{9}EG$";
+            readonly confidence: "low";
+            readonly checksum: "s10";
+            readonly preferred: true;
         }];
     };
     readonly ekart: {

package/dist/generated/catalog.js

@@ -9296,7 +9296,9 @@ export const CARRIER_CATALOG = {
         "timezone": "Africa/Cairo",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "egypt-post",
+            "recognitionRank": 944,
+            "localClocks": true
         },
         "canaryUrl": "https://egyptpost.gov.eg/en-us/home/",
         "trackingSearchUrl": "https://egyptpost.gov.eg/en-us/home/",
@@ -9316,6 +9318,12 @@ export const CARRIER_CATALOG = {
             {
                 "pattern": "^(?:ENO|EXP|RCC)\\d{8}EG$",
                 "confidence": "low"
+            },
+            {
+                "pattern": "^[A-Z]{2}\\d{9}EG$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
             }
         ]
     },
@@ -20875,7 +20883,7 @@ export const DETECTION_RULE_IDS = {
     "ecms-express": ["ecms-express-1"],
     "econt": [],
     "ecourier": ["ecourier-1"],
-    "egypt-post": ["egypt-post-1"],
+    "egypt-post": ["egypt-post-1", "egypt-post-s10"],
     "ekart": ["ekart-ecommerce"],
     "elta": ["elta-s10"],
     "emile": ["emile-1"],

package/dist/generated/recognition.js

@@ -62,6 +62,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "early-bird": 350,
     "econt": 290,
     "ecoscooting": 655,
+    "egypt-post": 944,
     "elta": 150,
     "emile": 480,
     "ems-vietnam": 962,

package/dist/generated/registry.js

@@ -85,6 +85,7 @@ import { adapter as dynalogic } from '../carriers/dynalogic/adapter.js';
 import { adapter as earlyBird } from '../carriers/early-bird/adapter.js';
 import { adapter as econt } from '../carriers/econt/adapter.js';
 import { adapter as ecoscooting } from '../carriers/ecoscooting/adapter.js';
+import { adapter as egyptPost } from '../carriers/egypt-post/adapter.js';
 import { adapter as ekart } from '../carriers/ekart/adapter.js';
 import { adapter as elta } from '../carriers/elta/adapter.js';
 import { adapter as emile } from '../carriers/emile/adapter.js';
@@ -358,6 +359,7 @@ export const REGISTRY = {
         "early-bird": earlyBird,
         "econt": econt,
         "ecoscooting": ecoscooting,
+        "egypt-post": egyptPost,
         "ekart": ekart,
         "elta": elta,
         "emile": emile,
@@ -691,7 +693,7 @@ export const REGISTRY = {
         "econt": "econt",
         "ecoscooting": "ecoscooting",
         "ecourier": "universal",
-        "egypt-post": "universal",
+        "egypt-post": "egypt-post",
         "ekart": "ekart",
         "elta": "elta",
         "emile": "emile",

package/dist/server/openapi.json

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

package/package.json

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