universal-parcel-scraper 0.78.0-main.939 → 0.80.0-main.943

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 **135 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **137 dedicated adapters** and **5 universal fallbacks**
 
 <sub>207 catalog entries · 66 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 3,852 such statuses, each filed under one stage.
+The carrier folders record 3,887 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

@@ -4808,12 +4808,24 @@
     "timezone": "Europe/Istanbul",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "aras-kargo",
+      "recognitionRank": 67,
+      "localClocks": true
     },
-    "canaryUrl": "https://www.araskargo.com.tr/",
-    "trackingUrlTemplate": "https://www.araskargo.com.tr/",
+    "canaryUrl": "https://kargotakip.araskargo.com.tr/mainpage.aspx",
+    "trackingUrlTemplate": "https://kargotakip.araskargo.com.tr/mainpage.aspx?code={trackingNumber}",
     "trackingSearchUrl": "https://www.araskargo.com.tr/",
-    "linkRules": [],
+    "linkRules": [
+      {
+        "domains": [
+          "kargotakip.araskargo.com.tr"
+        ],
+        "pathPattern": "^/mainpage\\.aspx$",
+        "params": [
+          "code"
+        ]
+      }
+    ],
     "detectionRules": []
   },
   "box-now": {
@@ -8285,7 +8297,9 @@
     "timezone": "Europe/Istanbul",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "yurtici-kargo",
+      "recognitionRank": 66,
+      "localClocks": true
     },
     "canaryUrl": "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula",
     "trackingUrlTemplate": "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula?code={trackingNumber}",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 207,
-  "activeAdapters": 135,
+  "activeAdapters": 137,
   "countries": 66,
   "referenceCarriers": 100,
   "comparison": {

package/dist/browser/scraper.js

@@ -3937,12 +3937,18 @@ var ye = {
 		timezone: "Europe/Istanbul",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "aras-kargo",
+			recognitionRank: 67,
+			localClocks: !0
 		},
-		canaryUrl: "https://www.araskargo.com.tr/",
-		trackingUrlTemplate: "https://www.araskargo.com.tr/",
+		canaryUrl: "https://kargotakip.araskargo.com.tr/mainpage.aspx",
+		trackingUrlTemplate: "https://kargotakip.araskargo.com.tr/mainpage.aspx?code={trackingNumber}",
 		trackingSearchUrl: "https://www.araskargo.com.tr/",
-		linkRules: [],
+		linkRules: [{
+			domains: ["kargotakip.araskargo.com.tr"],
+			pathPattern: "^/mainpage\\.aspx$",
+			params: ["code"]
+		}],
 		detectionRules: []
 	},
 	"box-now": {
@@ -6522,7 +6528,9 @@ var ye = {
 		timezone: "Europe/Istanbul",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "yurtici-kargo",
+			recognitionRank: 66,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula",
 		trackingUrlTemplate: "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula?code={trackingNumber}",
@@ -11707,6 +11715,7 @@ function gc(e) {
 var _c = {
 	"acs-courier": 57,
 	aliexpress: 14,
+	"aras-kargo": 67,
 	"australia-post": 6,
 	"austrian-post": 39,
 	"box-now": 48,
@@ -11772,7 +11781,8 @@ var _c = {
 	tnt: 44,
 	ukrposhta: 5,
 	uniuni: 33,
-	venipak: 63
+	venipak: 63,
+	"yurtici-kargo": 66
 }, vc = 5;
 function yc(e) {
 	let t = y(e);

package/dist/carriers/aras-kargo/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 legacy tracker's link for one parcel, the one merchants send. */
+export declare function arasTrackingUrl(raw: string): string;
+export declare class ArasKargoTracker {
+    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/aras-kargo/adapter.js

@@ -0,0 +1,105 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { IndeterminateError, SchemaError } 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 { arasWaybillFrame, normalizeArasNumber, parseAras, parseArasLookup, PROVIDER } from './parser.js';
+const ORIGIN = 'https://kargotakip.araskargo.com.tr';
+// Each page is under 30 kB; a long history adds a few hundred bytes a row.
+const MAX_BYTES = 512 * 1024;
+const REDIRECTS = [301, 302, 303, 307, 308];
+const COOKIE = /^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,64})=([\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]{0,1024})$/;
+const MAX_COOKIES = 16;
+/** The legacy tracker's link for one parcel, the one merchants send. */
+export function arasTrackingUrl(raw) {
+    return `${ORIGIN}/mainpage.aspx?${new URLSearchParams({ code: normalizeArasNumber(raw) })}`;
+}
+/** Keeps each cookie the tracker sets, by name, as a browser would send it back. */
+function keepCookies(jar, response) {
+    for (const header of response.headers.getSetCookie()) {
+        const match = COOKIE.exec(header.split(';', 1)[0].trim());
+        if (match)
+            jar.set(match[1], match[2]);
+    }
+    if (jar.size > MAX_COOKIES)
+        throw new SchemaError(PROVIDER, 'Aras Kargo set too many cookies');
+}
+/** Whether a reply sends the browser on to this page of the tracker. */
+function redirectsTo(response, page) {
+    if (!REDIRECTS.includes(response.status))
+        return false;
+    const location = response.headers.get('location');
+    if (!location || location.length > 200)
+        return false;
+    try {
+        const url = new URL(location, ORIGIN);
+        return url.origin === ORIGIN && url.pathname.toLowerCase() === page && !url.search && !url.hash && !url.username;
+    }
+    catch {
+        return false;
+    }
+}
+export class ArasKargoTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeArasNumber(raw);
+        // The tracker keeps the parcel in a session: the lookup page finds it and
+        // redirects to the tracking page, whose frames read it from the session.
+        // The load balancer's cookie keeps every request on the server that holds it.
+        const read = async (signal, timeoutMs) => {
+            const deadline = performance.now() + timeoutMs;
+            const jar = new Map();
+            const get = async (path) => {
+                const headers = {
+                    'User-Agent': userAgentOf(this.options.userAgent), Accept: 'text/html', 'Accept-Language': 'tr-TR,tr;q=0.9',
+                };
+                if (jar.size)
+                    headers.Cookie = [...jar].map(([name, value]) => `${name}=${value}`).join('; ');
+                const { response, bytes } = await fetchBounded(`${ORIGIN}/${path}`, { signal, headers }, {
+                    provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(deadline - performance.now())), maxBytes: MAX_BYTES,
+                    redirect: 'manual', allowHttpStatuses: [...REDIRECTS, 404, 410], fetcher: this.options.fetcher,
+                });
+                keepCookies(jar, response);
+                return { response, html: () => decodeText(bytes) };
+            };
+            const lookup = await get(`mainpage.aspx?${new URLSearchParams({ code: number })}`);
+            if (lookup.response.status === 200)
+                parseArasLookup(lookup.html(), number);
+            if (!redirectsTo(lookup.response, '/kargotakip.aspx'))
+                throw new IndeterminateError(PROVIDER, 'Aras Kargo tracker moved');
+            if (!jar.has('ASP.NET_SessionId'))
+                throw new IndeterminateError(PROVIDER, 'Aras Kargo did not open a session');
+            const tracker = await get('kargotakip.aspx');
+            // Without the shipment in its session, the tracking page sends the browser back to the lookup.
+            if (tracker.response.status !== 200)
+                throw new IndeterminateError(PROVIDER, 'Aras Kargo tracking page is unavailable');
+            const summary = await get(arasWaybillFrame(tracker.html()));
+            if (summary.response.status !== 200)
+                throw new IndeterminateError(PROVIDER, 'Aras Kargo shipment summary is unavailable');
+            // The movements frame reads the shipment the summary frame put in the session.
+            const movements = await get('CargoInfoTransactionAndRedirection.aspx');
+            if (movements.response.status !== 200)
+                throw new IndeterminateError(PROVIDER, 'Aras Kargo shipment movements are unavailable');
+            return parseAras(summary.html(), movements.html(), number);
+        };
+        // A lookup that fails to reach Aras, or hangs, starts again in a new
+        // session: the first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'aras-kargo', 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 ArasKargoTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'aras-kargo', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeArasNumber(number))),
+    };
+};

package/dist/carriers/aras-kargo/carrier.json

@@ -16,19 +16,78 @@
   "timezone": "Europe/Istanbul",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "aras-kargo",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 67
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "eta"
+  ],
   "portal": {
-    "url": "https://www.araskargo.com.tr/",
+    "url": "https://kargotakip.araskargo.com.tr/mainpage.aspx?code={trackingNumber}",
     "searchUrl": "https://www.araskargo.com.tr/",
-    "canaryUrl": "https://www.araskargo.com.tr/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "canaryUrl": "https://kargotakip.araskargo.com.tr/mainpage.aspx",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "signatory",
+      "delivery_pin",
+      "recipient_verification",
+      "payment_details",
+      "invoice_reference",
+      "volume",
+      "parcel_count",
+      "progress_rail",
+      "delivery_comments",
+      "customer_messages"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "signatory",
+      "delivery_pin",
+      "recipient_verification",
+      "payment_details",
+      "invoice_reference",
+      "volume",
+      "parcel_count",
+      "progress_rail",
+      "delivery_comments",
+      "customer_messages"
+    ],
+    "unavailable": [
+      "pickup_point",
+      "offset_timestamps"
+    ]
   },
-  "links": [],
+  "links": [
+    {
+      "domains": [
+        "kargotakip.araskargo.com.tr"
+      ],
+      "pathPattern": "^/mainpage\\.aspx$",
+      "params": [
+        "code"
+      ]
+    }
+  ],
   "detection": []
 }

package/dist/carriers/aras-kargo/parser.d.ts

@@ -0,0 +1,20 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Aras Kargo";
+/** A thirteen-digit Aras Kargo tracking number. */
+export declare function normalizeArasNumber(raw: string): string;
+/**
+ * The lookup page's answer when it does not open the tracker: its notice
+ * for a number it does not know, over the form for that number. Anything else
+ * says nothing about the parcel.
+ */
+export declare function parseArasLookup(html: string, raw: string): never;
+/** The summary frame of the tracking page, relative to the tracker. */
+export declare function arasWaybillFrame(html: string): string;
+/**
+ * The tracker's two frames for one parcel: the summary, with the current
+ * status, the delivery, the estimate and the days a delivery was not made,
+ * and the vehicle movements with any redirection. Names, the signatory, the
+ * delivery code, invoice and payment details and every free-text note are
+ * never read.
+ */
+export declare function parseAras(waybillHtml: string, movementsHtml: string, raw: string): CarrierResult;

package/dist/carriers/aras-kargo/parser.js

@@ -0,0 +1,205 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { 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 { arasStage } from './status.js';
+export const PROVIDER = 'Aras Kargo';
+/** Aras Kargo's tracking numbers, as on every label and sample seen. */
+const NUMBER = /^\d{13}$/;
+/** The lookup page's answer for a number it does not know. */
+const ABSENT = 'Girdiğiniz bilgiler için bir sonuç bulunamamıştır.';
+/** The summary frame the tracking page opens, bound to the shipment by an opaque id. */
+const WAYBILL_FRAME = /^CargoInfoWaybillAndDelivered\.aspx\?shipmentid=[0-9A-F]{32}&subekod=\d{0,6}$/;
+const MOVEMENTS_FRAME = 'CargoInfoTransactionAndRedirection.aspx';
+const MOVEMENT_HEADER = ['İşlem Tarihi', 'İl', 'Birim', 'İşlem Açıklaması'];
+const NON_DELIVERY_HEADER = ['Tarih', 'Teslim Edilememe Nedeni', 'Açıklama'];
+const REDIRECTION_HEADER = ['Tarih', 'Kargo Tipi', 'Kargo Durumu', 'Yönlendiren Birim', 'Yönlendirilen Birim', 'Yönlendirme Nedeni'];
+const MAX_ROWS = 300;
+const MAX_EVENTS = 100;
+const MOVING = new Set(['registered', 'accepted', 'in_transit', 'out_for_delivery']);
+/** A thirteen-digit Aras Kargo tracking number. */
+export function normalizeArasNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'Aras Kargo tracking numbers are thirteen digits');
+    return number;
+}
+/** A wall clock or a day in the page's day-first form ("3.10.2026 12:01:33", "05.10.2026"). It carries no offset. */
+function wallClock(text, form) {
+    const shapes = { day: 'd.M.yyyy', minute: 'd.M.yyyy H:mm', second: 'd.M.yyyy H:mm:ss' };
+    if (!/^[\d.: ]{8,19}$/.test(text))
+        return null;
+    // UTC only checks the calendar fields. No offset is assigned.
+    const parsed = DateTime.fromFormat(text, shapes[form], { zone: 'UTC' });
+    if (!parsed.isValid)
+        return null;
+    return parsed.toFormat(form === 'day' ? 'yyyy-MM-dd' : "yyyy-MM-dd'T'HH:mm:ss");
+}
+/** The one element with this id, or a schema failure. */
+function only($, selector, what) {
+    const found = $(selector);
+    if (found.length !== 1)
+        throw new SchemaError(PROVIDER, `Aras Kargo ${what} changed`);
+    return found;
+}
+/**
+ * A grid's rows as cell texts, after its header. A grid the server did not
+ * fill is missing from the page: the session did not carry the shipment.
+ */
+function grid($, id, header, what) {
+    const tables = $(`table#${id}`);
+    if (!tables.length)
+        throw new IndeterminateError(PROVIDER, `Aras Kargo did not return the ${what}`);
+    if (tables.length !== 1)
+        throw new SchemaError(PROVIDER, `Aras Kargo repeated the ${what}`);
+    const rows = tables.find('tr').toArray().map(row => $(row).children('td').toArray().map(cell => clean($(cell).text(), 200)));
+    if (!rows.length || rows[0].join('\u0000') !== header.join('\u0000'))
+        throw new SchemaError(PROVIDER, `Aras Kargo ${what} changed`);
+    if (rows.length - 1 > MAX_ROWS)
+        throw new SchemaError(PROVIDER, `Aras Kargo returned too many rows in the ${what}`);
+    return rows.slice(1).map(cells => {
+        if (cells.length !== header.length)
+            throw new SchemaError(PROVIDER, `Aras Kargo ${what} changed`);
+        return cells;
+    });
+}
+/** A movement's place: its unit, then its province unless the unit already names it. */
+function place(unit, province) {
+    if (!unit)
+        return province;
+    if (!province || unit === province || unit.startsWith(`${province} `))
+        return unit;
+    return `${unit}, ${province}`;
+}
+/**
+ * The lookup page's answer when it does not open the tracker: its notice
+ * for a number it does not know, over the form for that number. Anything else
+ * says nothing about the parcel.
+ */
+export function parseArasLookup(html, raw) {
+    const number = normalizeArasNumber(raw);
+    const $ = load(html);
+    const notice = $('span#Label1');
+    const form = $('form#form1');
+    if (notice.length === 1 && form.length === 1 && clean(notice.text(), 200) === ABSENT
+        && form.attr('action') === `./mainpage.aspx?code=${number}`) {
+        throw new NotFoundError(PROVIDER);
+    }
+    throw new IndeterminateError(PROVIDER, 'Aras Kargo did not open the tracker for this number');
+}
+/** The summary frame of the tracking page, relative to the tracker. */
+export function arasWaybillFrame(html) {
+    const $ = load(html);
+    const panels = $('#tabPanels');
+    if (!panels.length)
+        throw new IndeterminateError(PROVIDER, 'Aras Kargo did not return its tracking page');
+    const waybill = only($, 'iframe#panel0', 'tracking page').attr('src') ?? '';
+    const movements = only($, 'iframe#panel1', 'tracking page').attr('data-src') ?? '';
+    if (!WAYBILL_FRAME.test(waybill) || movements !== MOVEMENTS_FRAME)
+        throw new SchemaError(PROVIDER, 'Aras Kargo tracking page changed');
+    return waybill;
+}
+/** Each frame names the number it answers for; an empty one did not get the shipment. */
+function bind($, selector, number, what) {
+    if ($('html').attr('lang') !== 'tr')
+        throw new SchemaError(PROVIDER, 'Aras Kargo tracking page changed language');
+    const shown = $(selector);
+    if (shown.length > 1)
+        throw new SchemaError(PROVIDER, `Aras Kargo ${what} changed`);
+    const text = clean(shown.text(), 80);
+    if (!text)
+        throw new IndeterminateError(PROVIDER, `Aras Kargo did not return the ${what}`);
+    if (normalizeTrackingNumber(text) !== number)
+        throw new SchemaError(PROVIDER, 'Aras Kargo returned a different parcel');
+}
+/**
+ * The tracker's two frames for one parcel: the summary, with the current
+ * status, the delivery, the estimate and the days a delivery was not made,
+ * and the vehicle movements with any redirection. Names, the signatory, the
+ * delivery code, invoice and payment details and every free-text note are
+ * never read.
+ */
+export function parseAras(waybillHtml, movementsHtml, raw) {
+    const number = normalizeArasNumber(raw);
+    const summary = load(waybillHtml);
+    const movements = load(movementsHtml);
+    bind(summary, '#labelShipmentCode', number, 'shipment summary');
+    bind(movements, '.sno-value', number, 'shipment movements');
+    const status = clean(only(summary, 'span#Son_Durum', 'shipment summary').text(), 120);
+    const deliveredText = clean(only(summary, 'span#Teslim_Tarihi', 'shipment summary').text(), 40);
+    const branch = clean(only(summary, 'span#varis_subesi', 'shipment summary').text(), 80);
+    const plannedText = clean(only(summary, 'span#planlanan_teslim_tarihi', 'shipment summary').text(), 40);
+    const scans = [];
+    const seen = new Set();
+    // Within a day, rows dated by the day (order 1) follow the clocked movements (0), and the delivery (2) ends it.
+    const add = (local, description, location, order) => {
+        const event = { local_time: local, description, ...(location ? { location } : {}) };
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const stage = arasStage(description);
+        if (stage)
+            Object.assign(event, { stage, stage_source: 'carrier_map' });
+        scans.push({ event, local, order });
+    };
+    for (const [time, province, unit, description] of grid(movements, 'transactionsDataGrid', MOVEMENT_HEADER, 'vehicle movements')) {
+        const local = wallClock(time, 'second');
+        if (!local || !description)
+            throw new SchemaError(PROVIDER, 'Aras Kargo returned an invalid movement');
+        add(local, description, place(unit, province), 0);
+    }
+    // A redirection's reason follows its state in brackets.
+    for (const [date, , state, from, , cause] of grid(movements, 'redirectionDataGrid', REDIRECTION_HEADER, 'redirections')) {
+        const day = wallClock(date, 'day');
+        if (!day || !state)
+            throw new SchemaError(PROVIDER, 'Aras Kargo returned an invalid redirection');
+        const reason = cause.replace(/[()]/g, '').trim();
+        add(day, reason ? `${state} (${reason})` : state, from, 1);
+    }
+    // The third cell is the courier's free-text note.
+    for (const [date, reason] of grid(summary, 'notDeliveredDataGrid', NON_DELIVERY_HEADER, 'failed deliveries')) {
+        const day = wallClock(date, 'day');
+        if (!day || !reason)
+            throw new SchemaError(PROVIDER, 'Aras Kargo returned an invalid failed delivery');
+        add(day, reason, '', 1);
+    }
+    if (deliveredText) {
+        const local = wallClock(deliveredText, 'minute');
+        if (!local || !status)
+            throw new SchemaError(PROVIDER, 'Aras Kargo returned an invalid delivery time');
+        add(local, status, branch, 2);
+    }
+    // Newest first. The movement list comes sorted as text, not by time.
+    const day = (scan) => scan.local.slice(0, 10);
+    scans.sort((left, right) => day(left) !== day(right) ? (day(left) < day(right) ? 1 : -1)
+        : left.order !== right.order ? right.order - left.order
+            : left.local < right.local ? 1 : left.local > right.local ? -1 : 0);
+    const events = scans.map(({ event }) => event);
+    const newest = events[0];
+    const newestDay = scans[0] ? day(scans[0]) : null;
+    if (!status && !newest)
+        throw new NoHistoryError(PROVIDER);
+    // The current status settles a delivery. Otherwise a failed delivery after
+    // the last movement is the parcel's news, though the status still has it
+    // at the delivery branch.
+    const current = status ? arasStage(status) : newest.stage;
+    const failed = current !== 'delivered' && newest?.stage === 'failed_attempt';
+    const stage = failed ? 'failed_attempt' : current;
+    const text = failed ? newest.description : status || newest.description;
+    // The planned day is an estimate: it goes once the parcel stops moving or the day is behind its news.
+    const planned = wallClock(plannedText, 'day');
+    const expected = stage && MOVING.has(stage) && planned && (!newestDay || planned >= newestDay) ? planned : null;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: 'carrier_map' } : {}),
+        last_status_text: text,
+        last_update: null,
+        ...(scans[0] ? { last_update_local: scans[0].local } : {}),
+        expected_delivery: expected,
+        ...(events.length ? {} : { summary_only: true }),
+        events: events.slice(0, MAX_EVENTS),
+    };
+}

package/dist/carriers/aras-kargo/status.d.ts

@@ -0,0 +1,25 @@
+import type { Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/**
+ * The tracker's wording, mapped whole. It gives no status codes. "Son Durum"
+ * is the parcel's current status; the delivery is read from it, as the
+ * movement list stops at the delivery branch.
+ */
+export declare const ARAS_STATUSES: Readonly<Record<string, Stage>>;
+/**
+ * The vehicle movements ("Araç Hareketleri"): loading and unloading at a
+ * branch ("şube") or a transfer centre ("aktarma"), and bagging there. The
+ * page spells some without Turkish letters.
+ */
+export declare const ARAS_MOVEMENTS: Readonly<Record<string, Stage>>;
+/** The reasons a delivery was not made ("Teslim Edilememe Nedeni"), one row a day. */
+export declare const ARAS_NON_DELIVERIES: Readonly<Record<string, Stage>>;
+/**
+ * A redirection's state ("Kargo Durumu"). The parser adds the reason in
+ * brackets, and the map reads the state without it.
+ */
+export declare const ARAS_REDIRECTIONS: Readonly<Record<string, Stage>>;
+/** The stage the tracker's wording gives a status or a scan, if any. */
+export declare function arasStage(wording: string): Stage | undefined;
+/** The tracker's scans carry wording and no code. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/aras-kargo/status.js

@@ -0,0 +1,59 @@
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * The tracker's wording, mapped whole. It gives no status codes. "Son Durum"
+ * is the parcel's current status; the delivery is read from it, as the
+ * movement list stops at the delivery branch.
+ */
+export const ARAS_STATUSES = {
+    // At the branch that took the parcel in.
+    'ÇIKIŞ ŞUBESİNDE': 'accepted',
+    'YOLDA': 'in_transit',
+    // At the branch that delivers it, also after a failed delivery.
+    'TESLİMAT ŞUBESİNDE': 'in_transit',
+    'TESLİM EDİLDİ': 'delivered',
+};
+/**
+ * The vehicle movements ("Araç Hareketleri"): loading and unloading at a
+ * branch ("şube") or a transfer centre ("aktarma"), and bagging there. The
+ * page spells some without Turkish letters.
+ */
+export const ARAS_MOVEMENTS = {
+    'ŞUBEDE ARAÇ YÜKLEME': 'in_transit',
+    'ŞUBEDE ARAÇ İNDİRME': 'in_transit',
+    'AKTARMADA HAT ARACI YÜKLEME': 'in_transit',
+    'AKTARMADA HAT ARACI İNDİRME': 'in_transit',
+    'AKTARMADA SUBE ARACI YUKLEME': 'in_transit',
+    'AKTARMADA SUBE ARACI INDIRME': 'in_transit',
+    'AKTARMADA TORBA DOLDURMA': 'in_transit',
+};
+/** The reasons a delivery was not made ("Teslim Edilememe Nedeni"), one row a day. */
+export const ARAS_NON_DELIVERIES = {
+    'TESLİMAT GÜN İÇERİSİNDE YAPILAMADI': 'failed_attempt',
+    'TATİL DOLAYISIYLA TESLİMAT YAPILAMADI': 'failed_attempt',
+    'UĞRAMA NOTU BIRAKILDI (1-2)': 'failed_attempt',
+    'ALICI ADRESİ DAĞITIM ALANI DIŞINDA': 'failed_attempt',
+};
+/**
+ * A redirection's state ("Kargo Durumu"). The parser adds the reason in
+ * brackets, and the map reads the state without it.
+ */
+export const ARAS_REDIRECTIONS = {
+    'YÖNLENDİRİLDİ': 'in_transit',
+};
+/** A redirection's reason, which the parser adds in brackets. */
+const REASON = /\s*\([^()]*\)$/;
+const WORDINGS = new Map(Object.entries({ ...ARAS_STATUSES, ...ARAS_MOVEMENTS, ...ARAS_NON_DELIVERIES })
+    .map(([wording, stage]) => [normalizeStatusWording(wording), stage]));
+const REDIRECTIONS = new Map(Object.entries(ARAS_REDIRECTIONS).map(([wording, stage]) => [normalizeStatusWording(wording), stage]));
+function stageOf(wording) {
+    return WORDINGS.get(wording) ?? REDIRECTIONS.get(wording.replace(REASON, ''));
+}
+/** The stage the tracker's wording gives a status or a scan, if any. */
+export function arasStage(wording) {
+    return stageOf(normalizeStatusWording(wording));
+}
+/** The tracker's scans carry wording and no code. */
+export const statusMap = {
+    stage: (code, wording) => code ? undefined : stageOf(wording),
+    gaps: [],
+};