universal-parcel-scraper 0.191.0 → 0.192.0-main.1354

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 **272 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **273 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,886 such statuses, each filed under one stage.
+The carrier folders record 9,895 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

@@ -5933,7 +5933,9 @@
     "timezone": "Asia/Riyadh",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "aymakan",
+      "recognitionRank": 942,
+      "localClocks": true
     },
     "canaryUrl": "https://aymakan.com/tracking",
     "trackingUrlTemplate": "https://aymakan.com/tracking/{trackingNumber}",

package/data/coverage-summary.json

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

package/dist/browser/scraper.js

@@ -4797,7 +4797,9 @@ var Ae = {
 		timezone: "Asia/Riyadh",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "aymakan",
+			recognitionRank: 942,
+			localClocks: !0
 		},
 		canaryUrl: "https://aymakan.com/tracking",
 		trackingUrlTemplate: "https://aymakan.com/tracking/{trackingNumber}",
@@ -21116,6 +21118,7 @@ var nl = {
 	"aras-kargo": 420,
 	"australia-post": 500,
 	"austrian-post": 830,
+	aymakan: 942,
 	"blue-express": 971,
 	bosta: 951,
 	"box-now": 250,

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

@@ -0,0 +1,16 @@
+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 tracker's page for one number, which its tracking form opens. */
+export declare const AYMAKAN_TRACKING = "https://aymakan.com/tracking/";
+export declare class AymakanTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+        now?: () => number;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/aymakan/adapter.js

@@ -0,0 +1,43 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { 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 { AYMAKAN_MAX_BYTES, normalizeAymakanNumber, parseAymakan, PROVIDER } from './parser.js';
+/** The tracker's page for one number, which its tracking form opens. */
+export const AYMAKAN_TRACKING = 'https://aymakan.com/tracking/';
+const REDIRECTS = [301, 302, 303, 307, 308];
+export class AymakanTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeAymakanNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(`${AYMAKAN_TRACKING}${encodeURIComponent(number)}`, { signal, headers: {
+                    Accept: 'text/html', 'Accept-Language': 'en', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: AYMAKAN_MAX_BYTES, redirect: 'manual',
+                fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            // The page answers HTTP 200 for a number it does not know; a redirect or a 404 is a moved route.
+            if (response.status !== 200)
+                throw new TransportError(PROVIDER, 'AyMakan tracking page moved');
+            return parseAymakan(decodeText(bytes), number, (this.options.now ?? Date.now)());
+        };
+        // A read that fails to reach the site, or hangs, gets one more: the first gets half of the budget.
+        return runSteps({ carrier: 'aymakan', budgetMs: context.budgetMs ?? 20_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 AymakanTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'aymakan', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeAymakanNumber(number))),
+    };
+};

package/dist/carriers/aymakan/carrier.json

@@ -17,18 +17,53 @@
   "timezone": "Asia/Riyadh",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "aymakan",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 942
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history"
+  ],
   "portal": {
     "url": "https://aymakan.com/tracking/{trackingNumber}",
     "searchUrl": "https://aymakan.com/tracking",
     "canaryUrl": "https://aymakan.com/tracking",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "progress_rail",
+      "history",
+      "origin",
+      "destination",
+      "signatory"
+    ],
+    "scraped": [
+      "status",
+      "history"
+    ],
+    "discarded": [
+      "progress_rail",
+      "origin",
+      "destination",
+      "signatory"
+    ],
+    "unavailable": [
+      "location",
+      "scan_times",
+      "offset_timestamps",
+      "provider_code",
+      "eta",
+      "weight",
+      "delivered_at",
+      "proof_of_delivery",
+      "sender_name",
+      "recipient_name"
+    ]
   },
   "links": [
     {

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

@@ -0,0 +1,30 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "AyMakan";
+export declare const AYMAKAN_MAX_BYTES = 1000000;
+/** A number for AyMakan's tracker, in capitals as the page shows it; anything else is not one it issues. */
+export declare function normalizeAymakanNumber(raw: string): string;
+/** A Cloudflare challenge or block page in place of the tracker. */
+export declare function assertNotChallenged(html: string): void;
+/**
+ * The newest day a scan can carry: the lookup's day in Saudi Arabia, and one
+ * more in case the page dates scans in a zone further east.
+ */
+export declare function latestScanDay(now: number): string;
+/**
+ * A scan's day, which the page writes "Sat, Apr 05", without a year. The year
+ * is the latest one, not after `latest`, in which that day falls on that
+ * weekday: a day comes round on the same weekday after five years at the
+ * soonest, so a scan less than five years old is dated exactly.
+ */
+export declare function aymakanDay(label: string, latest: string): string;
+/** A timeline entry's wording, without who took the parcel or a phone number. */
+export declare function aymakanWording(text: string): string;
+/**
+ * The tracker's page for one number, `aymakan.com/tracking/{number}`, which
+ * the site renders on its server: the shipment's status over "Tracking #:" and
+ * the number, a progress rail, the route, masked parties and the timeline. A
+ * number it does not know gets "No shipment found" under its search form,
+ * which keeps the number. The route, the rail and who took the parcel are not
+ * kept. `now` is the lookup's time, which sets the years of the scans' days.
+ */
+export declare function parseAymakan(html: string, raw: string, now?: number): CarrierResult;

package/dist/carriers/aymakan/parser.js

@@ -0,0 +1,154 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { ChallengeError, IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { calendarDay } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { aymakanMappedStage, aymakanStage } from './status.js';
+export const PROVIDER = 'AyMakan';
+// The pages are 50 to 90 kB.
+export const AYMAKAN_MAX_BYTES = 1_000_000;
+// `AY` and nine to eleven digits; older shipments have a bare six-digit number.
+const NUMBER = /^(?:AY\d{9,11}|\d{6})$/;
+// Cloudflare's challenge and block pages, which the site's CDN can serve in place of the tracker.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|\/cdn-cgi\/challenge-platform\/|<title>\s*(?:Just a moment|Attention Required!)/i;
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const DAY = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{2})$/;
+// Every weekday, month and day comes round within 28 years, 29 February included.
+const CALENDAR_CYCLE_YEARS = 28;
+const TRACKING = /^Tracking #:\s*(\S+)$/;
+const NOT_FOUND = 'No shipment found';
+// Who took the parcel, after a delivery's wording: "… - Received by {name}".
+const RECEIVER = /\s*-\s*(?:received|collected|signed|retrieved) by\b[\s\S]*$/i;
+// A run of nine or more digits, with spaces, brackets, dots or hyphens between them, as phone numbers are written.
+const PHONE = /(?<![A-Z\d])\+?\d(?:[\s().-]{0,2}\d){8,}(?![A-Z\d])/gi;
+const MAX_ROWS = 300;
+const MAX_EVENTS = 100;
+/** A number for AyMakan's tracker, in capitals as the page shows it; anything else is not one it issues. */
+export function normalizeAymakanNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw).toUpperCase() : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'AyMakan numbers are AY and nine to eleven digits, or six digits');
+    return number;
+}
+/** A Cloudflare challenge or block page in place of the tracker. */
+export function assertNotChallenged(html) {
+    if (CHALLENGE.test(html.slice(0, 64_000)))
+        throw new ChallengeError(PROVIDER, 'AyMakan answered with a browser check');
+}
+/**
+ * The newest day a scan can carry: the lookup's day in Saudi Arabia, and one
+ * more in case the page dates scans in a zone further east.
+ */
+export function latestScanDay(now) {
+    return DateTime.fromMillis(now, { zone: 'Asia/Riyadh' }).plus({ days: 1 }).toISODate();
+}
+/**
+ * A scan's day, which the page writes "Sat, Apr 05", without a year. The year
+ * is the latest one, not after `latest`, in which that day falls on that
+ * weekday: a day comes round on the same weekday after five years at the
+ * soonest, so a scan less than five years old is dated exactly.
+ */
+export function aymakanDay(label, latest) {
+    const match = DAY.exec(label);
+    if (!match)
+        throw new SchemaError(PROVIDER, 'AyMakan returned an invalid scan date');
+    const month = MONTHS.indexOf(match[2]) + 1;
+    const weekday = WEEKDAYS.indexOf(match[1]);
+    const newest = Number(latest.slice(0, 4));
+    for (let year = newest; year >= newest - CALENDAR_CYCLE_YEARS; year -= 1) {
+        const day = calendarDay(year, month, Number(match[3]));
+        if (day && day <= latest && new Date(`${day}T00:00:00Z`).getUTCDay() === weekday)
+            return day;
+    }
+    throw new SchemaError(PROVIDER, 'AyMakan returned an invalid scan date');
+}
+/** A timeline entry's wording, without who took the parcel or a phone number. */
+export function aymakanWording(text) {
+    return clean(clean(text, 500).replace(RECEIVER, '').replace(PHONE, ''), 300).replace(/[\s,;:\-–]+$/, '');
+}
+/** The timeline's entries, newest first as the page lists them: a heading with the wording and the day under it. */
+function eventsOf($, main, latest) {
+    const titles = main.find('h3').filter((_, heading) => clean($(heading).text(), 40) === 'Timeline');
+    const timeline = titles.closest('aside');
+    if (titles.length !== 1 || timeline.length !== 1)
+        throw new SchemaError(PROVIDER, 'AyMakan returned a page without its timeline');
+    const headings = timeline.find('h4').toArray();
+    if (headings.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'AyMakan returned an oversized timeline');
+    const seen = new Set();
+    const events = [];
+    for (const heading of headings) {
+        const days = $(heading).siblings('p');
+        const description = aymakanWording($(heading).text());
+        if (days.length !== 1 || !description)
+            throw new SchemaError(PROVIDER, 'AyMakan returned an invalid timeline entry');
+        const day = aymakanDay(clean(days.text(), 40), latest);
+        // Scans are dated to the day: the same wording twice on one day adds nothing.
+        const key = `${day} ${description}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const staged = aymakanStage(description);
+        events.push({ local_time: day, description, ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}) });
+    }
+    return events;
+}
+/**
+ * The tracker's page for one number, `aymakan.com/tracking/{number}`, which
+ * the site renders on its server: the shipment's status over "Tracking #:" and
+ * the number, a progress rail, the route, masked parties and the timeline. A
+ * number it does not know gets "No shipment found" under its search form,
+ * which keeps the number. The route, the rail and who took the parcel are not
+ * kept. `now` is the lookup's time, which sets the years of the scans' days.
+ */
+export function parseAymakan(html, raw, now = Date.now()) {
+    const number = normalizeAymakanNumber(raw);
+    assertNotChallenged(html);
+    const $ = load(html);
+    const main = $('main');
+    if (main.length !== 1)
+        throw new SchemaError(PROVIDER, 'AyMakan returned an unexpected page');
+    const searched = clean(main.find('form input').first().attr('value') ?? '', 64).toUpperCase();
+    const labels = main.find('p').filter((_, line) => TRACKING.test(clean($(line).text(), 100)));
+    if (labels.length === 0) {
+        const missing = main.find('h3').filter((_, heading) => clean($(heading).text(), 60) === NOT_FOUND).length === 1;
+        if (missing && searched === number)
+            throw new NotFoundError(PROVIDER);
+        if (missing)
+            throw new IndeterminateError(PROVIDER, 'AyMakan answered for another search');
+        throw new SchemaError(PROVIDER, 'AyMakan returned a page without a shipment');
+    }
+    if (labels.length > 1)
+        throw new SchemaError(PROVIDER, 'AyMakan returned several shipments');
+    const shown = TRACKING.exec(clean(labels.text(), 100))[1].toUpperCase();
+    if (shown !== number)
+        throw new IndeterminateError(PROVIDER, 'AyMakan answered for another shipment');
+    const summary = clean(labels.siblings('h3').text(), 120);
+    if (!summary)
+        throw new SchemaError(PROVIDER, 'AyMakan returned a shipment without its status');
+    const events = eventsOf($, main, latestScanDay(now));
+    const newest = events[0];
+    // The status over the shipment is the carrier's current one; the newest scan
+    // with a stage decides only a status the list does not know.
+    const listed = aymakanMappedStage(summary);
+    const scanned = events.find((event) => event.stage);
+    const worded = listed || scanned ? null : aymakanStage(summary);
+    const stage = (listed ?? scanned?.stage ?? worded?.stage);
+    const source = listed ? 'carrier_map' : scanned ? scanned.stage_source : worded?.source;
+    if (!newest && !stage)
+        throw new NoHistoryError(PROVIDER);
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: source ?? 'carrier_map' } : {}),
+        last_status_text: newest?.description ?? summary,
+        last_update: null,
+        last_update_local: typeof newest?.local_time === 'string' ? newest.local_time : null,
+        expected_delivery: null,
+        ...(newest ? {} : { summary_only: true }),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

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

@@ -0,0 +1,11 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/**
+ * The stage AyMakan's list gives a status label or a timeline description.
+ * The reverse pickups of returns and "Pending" are left to the shared rules.
+ */
+export declare function aymakanMappedStage(wording: string): Stage | undefined;
+/** A status's or scan's stage: the list's, else the shared wording rules', else nothing. */
+export declare function aymakanStage(wording: string): ClassifiedWording | null;
+/** What the map says about one status or scan, by its wording: the tracker shows no codes. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/aymakan/status.js

@@ -0,0 +1,92 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * AyMakan's statuses, from its list of status codes: the label the tracker
+ * shows over a shipment, the description its timeline shows for the scan, and
+ * the stage. A parcel is collected from the shipper's collection point, sorted
+ * at a hub and received at the delivering city's warehouse. Lockers, external
+ * partners and holds have statuses of their own. The tracker shows no codes.
+ */
+const STATUSES = [
+    ['AWB created at origin', 'Shipment is created at collection point', 'registered'], // AY-0001
+    ['Picked from Collection Point', 'Shipment was collected from collection point', 'accepted'], // AY-0002
+    ['Received at Warehouse', 'Shipment is received at hub', 'in_transit'], // AY-0003
+    ['Out for Delivery', 'Shipment is out for its final destination', 'out_for_delivery'], // AY-0004
+    ['Delivered', 'Shipment is delivered to customer', 'delivered'], // AY-0005
+    ['Not Delivered', 'Shipment delivery attempt failed', 'failed_attempt'], // AY-0006
+    ['Cancelled', 'Shipment was cancelled', 'exception'], // AY-0007
+    ['Returned', 'Shipment is returned to shipper', 'returned'], // AY-0008
+    ['In Transit', 'Shipment is in transit', 'in_transit'], // AY-0009
+    ['Delayed', 'Shipment is delayed upon customer request', 'exception'], // AY-0010
+    ['Cancelled', 'Shipment cancelled', 'exception'], // AY-0011
+    ['Missing Phone / Address', 'Missing consignee information', 'exception'], // AY-0013
+    // Back at the warehouse after failed attempts; it goes out again or back to the shipper.
+    ['Received Back in Warehouse', 'Returned after failed delivery attempts', 'exception'], // AY-0017
+    ['Out for Return to Shipper', 'Shipment is returning to shipper', 'returned'], // AY-0028
+    ['Pickup Cancelled', 'Pickup cancelled', 'exception'], // AY-0029
+    ['Assigned to Collection Driver', 'Driver assigned for collection', 'registered'], // AY-0039
+    ['No Answer', 'Customer did not answer', 'failed_attempt'], // AY-0040
+    ['Out of Network', 'Destination outside delivery network', 'exception'], // AY-0041
+    ['On Hold', 'Shipment is on hold', 'exception'], // AY-0050
+    ['Lost', 'Shipment lost', 'exception'], // AY-0058
+    ['Processing for Return', 'Processing return to shipper', 'returned'], // AY-0059
+    ['Waiting Address Validation', 'Shipment awaiting address validation', 'exception'], // AY-0064
+    ['Address Validated', 'Address validated', 'in_transit'], // AY-0065
+    ['Remote City', 'Awaiting remote area service day', 'in_transit'], // AY-0066
+    ['Arrived at Delivery Warehouse', 'Shipment arrived at delivery warehouse', 'in_transit'], // AY-0068
+    ['Created at External', 'Shipment created by external partner', 'registered'], // AY-0069
+    ['Picked Up - External', 'Picked up by external partner', 'accepted'], // AY-0070
+    ['Processing for Remote Area', 'Processing remote area shipment', 'in_transit'], // AY-0079
+    ['Return to Aymakan Warehouse', 'Returned to Aymakan warehouse', 'exception'], // AY-0084
+    ['Received in Clearing Department', 'Customs clearing', 'customs'], // AY-0088
+    ['Hold for Dispatch', 'Shipment on dispatch hold', 'exception'], // AY-0090
+    ['Cancelled by Consignee', 'Shipment cancelled by consignee', 'exception'], // AY-0091
+    ['Mailroom On Hold', 'Mailroom shipment on hold', 'exception'], // AY-0093
+    ['Mailroom Processing for Return', 'Mailroom return processing', 'returned'], // AY-0094
+    ['Scheduled Delivery', 'Delivery scheduled upon customer request', 'in_transit'], // AY-0095
+    ['Dispatch External', 'Dispatched to external carrier', 'in_transit'], // AY-0097
+    ['Arrived at Destination Warehouse', 'Shipment arrived at destination warehouse', 'in_transit'], // AY-0099
+    ['Cancelled by Shipper', 'Shipment cancelled by shipper', 'exception'], // AY-0105
+    ['Deposited to Locker', 'Shipment deposited into locker', 'ready_for_pickup'], // AY-0108
+    ['Locker Expired', 'Locker holding period expired', 'exception'], // AY-0109
+    ['Locker AWB Generated', 'Locker shipment created', 'registered'], // AY-0110
+    ['Out for Deposit', 'Driver is depositing shipment', 'out_for_delivery'], // AY-0111
+    ['Retrieved', 'Shipment retrieved from locker', 'delivered'], // AY-0112
+    ['Locker Cancelled', 'Locker delivery cancelled', 'exception'], // AY-0113
+    // The driver goes to collect the parcel from the shipper.
+    ['Out for Pickup', 'Driver out to collect shipment', 'registered'], // AY-0114
+    ['External Assigned', 'Assigned to external logistics provider', 'in_transit'], // AY-0116
+];
+/** A wording in `normalizeStatusWording` form, without the full stop some descriptions end with. */
+function key(wording) {
+    return normalizeStatusWording(wording).replace(/\s*\.$/, '');
+}
+const WORDINGS = new Map([
+    ...STATUSES.flatMap(([label, description, stage]) => [[key(label), stage], [key(description), stage]]),
+    // The timeline's wording for the creation of older shipments.
+    [key('Shipping Created'), 'registered'],
+]);
+// A receipt at a city's hub, warehouse or station, such as AY-0026's "Received at Riyadh
+// Warehouse", or older shipments' "Shipment is received at Riyadh hub".
+const RECEIVED = /^(?:shipment (?:is )?)?received (?:at|in) /;
+/**
+ * The stage AyMakan's list gives a status label or a timeline description.
+ * The reverse pickups of returns and "Pending" are left to the shared rules.
+ */
+export function aymakanMappedStage(wording) {
+    const normalized = key(wording);
+    return WORDINGS.get(normalized) ?? (RECEIVED.test(normalized) ? 'in_transit' : undefined);
+}
+/** A status's or scan's stage: the list's, else the shared wording rules', else nothing. */
+export function aymakanStage(wording) {
+    const mapped = aymakanMappedStage(wording);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+/** What the map says about one status or scan, by its wording: the tracker shows no codes. */
+export const statusMap = {
+    stage: (code, wording) => (code ? undefined : aymakanMappedStage(wording)),
+    gaps: [],
+};

package/dist/carriers/aymakan/statuses.json

@@ -11,9 +11,9 @@
     {"wording": "في مرحلة انتقالية", "stage": "in_transit", "language": "ar", "confirmedBy": "portal", "note": "Arabic progress-rail step for In Transit."},
     {"wording": "خارج للتوصيل", "stage": "out_for_delivery", "language": "ar", "confirmedBy": "portal", "note": "Arabic progress-rail step for Out for Delivery."},
     {"wording": "مرحلة التسليم", "stage": "delivered", "language": "ar", "confirmedBy": "portal", "note": "Arabic progress-rail step for Delivered."},
-    {"code": "AY-0001", "wording": "AWB created at origin", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table."},
+    {"code": "AY-0001", "wording": "AWB created at origin", "stage": "registered", "language": "en", "confirmedBy": "portal", "note": "Status over a shipment on the tracker; the label of AY-0001 in AyMakan's status table."},
     {"code": "AY-0002", "wording": "Picked from Collection Point", "stage": "accepted", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table."},
-    {"code": "AY-0003", "wording": "Received at Warehouse", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. Received at a hub."},
+    {"code": "AY-0003", "wording": "Received at Warehouse", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Status over a shipment on the tracker; the label of AY-0003 in AyMakan's status table. Received at a hub."},
     {"code": "AY-0006", "wording": "Not Delivered", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. A delivery attempt failed; a reason code follows."},
     {"code": "AY-0007", "wording": "Cancelled", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. AY-0011 has the same label."},
     {"code": "AY-0008", "wording": "Returned", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. Returned to the shipper."},
@@ -29,6 +29,15 @@
     {"code": "AY-0088", "wording": "Received in Clearing Department", "stage": "customs", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. Customs clearing."},
     {"code": "AY-0099", "wording": "Arrived at Destination Warehouse", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table."},
     {"code": "AY-0108", "wording": "Deposited to Locker", "stage": "ready_for_pickup", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table."},
-    {"code": "AY-0112", "wording": "Retrieved", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. Collected from the locker."}
+    {"code": "AY-0112", "wording": "Retrieved", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Status label in AyMakan's webhook status table. Collected from the locker."},
+    {"code": "AY-0002", "wording": "Shipment was collected from collection point", "stage": "accepted", "language": "en", "confirmedBy": "portal", "note": "Timeline entry; the description of AY-0002 in the status table."},
+    {"code": "AY-0003", "wording": "Shipment is received at hub", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Timeline entry; the description of AY-0003 in the status table."},
+    {"wording": "Shipment is received at Riyadh hub", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Timeline entry of older shipments, naming the hub's city."},
+    {"code": "AY-0026", "wording": "Received at Riyadh Warehouse", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Timeline entry; the label of AY-0026 in the status table. Other cities' warehouses have codes of their own."},
+    {"code": "AY-0009", "wording": "Shipment is in transit", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Timeline entry; the description of AY-0009 in the status table."},
+    {"code": "AY-0005", "wording": "Shipment is delivered to customer", "stage": "delivered", "language": "en", "confirmedBy": "portal", "note": "Timeline entry; the description of AY-0005. The tracker follows it with \" - Received by\" and who took the parcel, which the adapter drops."},
+    {"wording": "Shipping Created", "stage": "registered", "language": "en", "confirmedBy": "portal", "note": "Timeline entry for the creation of an older shipment."},
+    {"wording": "Shipment Created", "stage": "registered", "language": "en", "confirmedBy": "portal", "note": "Step of the current tracker's progress rail, which the adapter does not read."},
+    {"wording": "Picked Up", "stage": "accepted", "language": "en", "confirmedBy": "portal", "note": "Step of the current tracker's progress rail, which the adapter does not read."}
   ]
 }

package/dist/core/catalog/statusMaps.js

@@ -25,6 +25,7 @@ import { statusMap as apcOvernight } from '../../carriers/apc-overnight/status.j
 import { statusMap as aramexAu } from '../../carriers/aramex-au/status.js';
 import { statusMap as aramexNz } from '../../carriers/aramex-nz/status.js';
 import { statusMap as arasKargo } from '../../carriers/aras-kargo/status.js';
+import { statusMap as aymakan } from '../../carriers/aymakan/status.js';
 import { statusMap as blueExpress } from '../../carriers/blue-express/status.js';
 import { statusMap as bosta } from '../../carriers/bosta/status.js';
 import { statusMap as boxNow } from '../../carriers/box-now/status.js';
@@ -197,7 +198,7 @@ import { CARRIER_DEFINITIONS } from './definitions.js';
 export const STATUS_MAPS = {
     '17feia': seventeenFeia, '5post': fivePost, '99minutos': ninetynineMinutos, 'abf-freight': abfFreight, 'acs-courier': acsCourier, aliexpress,
     'allegro-one': allegroOne, 'an-post': anPost, andreani, anjun, anteraja, 'apc-overnight': apcOvernight, 'aramex-au': aramexAu, 'aramex-nz': aramexNz,
-    'aras-kargo': arasKargo, 'blue-express': blueExpress, bosta, 'box-now': boxNow, cacesa, cargus, cdek, cdl, celeritas, 'ceska-posta': ceskaPosta,
+    'aras-kargo': arasKargo, aymakan, 'blue-express': blueExpress, bosta, 'box-now': boxNow, cacesa, cargus, cdek, cdl, celeritas, 'ceska-posta': ceskaPosta,
     chilexpress, 'china-post': chinaPost, 'chit-chats': chitChats, chronopost, 'chunghwa-post': chunghwaPost, 'cj-logistics': cjLogistics,
     'cj-packet': cjPacket,
     coordinadora, 'correo-argentino': correoArgentino, 'correos-de-mexico': correosDeMexico, 'correos-spain': correosSpain,

package/dist/data/catalog.json

@@ -5933,7 +5933,9 @@
         "timezone": "Asia/Riyadh",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "aymakan",
+            "recognitionRank": 942,
+            "localClocks": true
         },
         "canaryUrl": "https://aymakan.com/tracking",
         "trackingUrlTemplate": "https://aymakan.com/tracking/{trackingNumber}",

package/dist/generated/catalog.d.ts

@@ -3981,7 +3981,9 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "Asia/Riyadh";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "aymakan";
+            readonly recognitionRank: 942;
+            readonly localClocks: true;
         };
         readonly canaryUrl: "https://aymakan.com/tracking";
         readonly trackingUrlTemplate: "https://aymakan.com/tracking/{trackingNumber}";

package/dist/generated/catalog.js

@@ -5934,7 +5934,9 @@ export const CARRIER_CATALOG = {
         "timezone": "Asia/Riyadh",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "aymakan",
+            "recognitionRank": 942,
+            "localClocks": true
         },
         "canaryUrl": "https://aymakan.com/tracking",
         "trackingUrlTemplate": "https://aymakan.com/tracking/{trackingNumber}",

package/dist/generated/recognition.js

@@ -16,6 +16,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "aras-kargo": 420,
     "australia-post": 500,
     "austrian-post": 830,
+    "aymakan": 942,
     "blue-express": 971,
     "bosta": 951,
     "box-now": 250,

package/dist/generated/registry.js

@@ -19,6 +19,7 @@ import { adapter as arasKargo } from '../carriers/aras-kargo/adapter.js';
 import { adapter as asendia } from '../carriers/asendia/adapter.js';
 import { adapter as australiaPost } from '../carriers/australia-post/adapter.js';
 import { adapter as austrianPost } from '../carriers/austrian-post/adapter.js';
+import { adapter as aymakan } from '../carriers/aymakan/adapter.js';
 import { adapter as blueDart } from '../carriers/blue-dart/adapter.js';
 import { adapter as blueExpress } from '../carriers/blue-express/adapter.js';
 import { adapter as bosta } from '../carriers/bosta/adapter.js';
@@ -293,6 +294,7 @@ export const REGISTRY = {
         "asendia": asendia,
         "australia-post": australiaPost,
         "austrian-post": austrianPost,
+        "aymakan": aymakan,
         "blue-dart": blueDart,
         "blue-express": blueExpress,
         "bosta": bosta,
@@ -584,7 +586,7 @@ export const REGISTRY = {
         "australia-post": "australia-post",
         "austrian-post": "austrian-post",
         "averitt": "universal",
-        "aymakan": "universal",
+        "aymakan": "aymakan",
         "azerpost": "universal",
         "azul-cargo": "universal",
         "bangladesh-post": "universal",

package/dist/server/openapi.json

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

package/package.json

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