universal-parcel-scraper 0.178.0-main.1306 → 0.181.0

package/dist/carriers/5post/numbers.json

@@ -12,7 +12,7 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -30,7 +30,7 @@
           "xpressbees"
         ]
       },
-      "note": "A vc.ru post about a lost FivePost parcel gives it as the parcel's tracking number."
+      "note": "A vc.ru post about a lost FivePost parcel gives it as the parcel's tracking number; 5Post's app finds the order."
     },
     {
       "number": "99990023667453",
@@ -43,7 +43,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -61,7 +61,7 @@
           "xpressbees"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "99990024107391",
@@ -74,7 +74,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -92,7 +92,7 @@
           "xpressbees"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "99880000719762",
@@ -105,7 +105,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -123,7 +123,7 @@
           "xpressbees"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "99880020264657",
@@ -136,7 +136,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -154,7 +154,7 @@
           "xpressbees"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "99110007024671",
@@ -167,7 +167,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -185,7 +185,7 @@
           "xpressbees"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "BX00000016018296FRW",
@@ -198,13 +198,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
         "confidence": "none"
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "BX00000016161928FRW",
@@ -217,13 +217,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
         "confidence": "none"
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "BX00000016412302FRW",
@@ -236,13 +236,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
         "confidence": "none"
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order."
     },
     {
       "number": "P03321461309",
@@ -255,7 +255,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -264,7 +264,7 @@
           "colis-prive"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request. Another capture of the same lookup names Avito as the shop."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order. Another capture of the same lookup names Avito as the shop."
     },
     {
       "number": "P06321818332",
@@ -277,7 +277,7 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -286,7 +286,7 @@
           "colis-prive"
         ]
       },
-      "note": "Looked up on 5Post's own tracker, as an archived address shows; the capture was not opened because the page loads results by a CAPTCHA-gated request. Another capture of the same lookup names Avito as the shop."
+      "note": "Looked up on 5Post's own tracker, as an archived address shows; 5Post's app finds the order. Another capture of the same lookup names Avito as the shop."
     }
   ]
 }

package/dist/carriers/5post/parser.d.ts

@@ -0,0 +1,23 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "5Post";
+export declare const FIVE_POST_MAX_BYTES: number;
+/**
+ * A 5Post number is the order number the shop gave the parcel, which 5Post
+ * matches whole and in upper case. Anything but letters and digits is not one.
+ */
+export declare function normalizeFivePostNumber(raw: string): string;
+/**
+ * The order 5Post lists under the whole number, from the reply of
+ * `GET /v3/mobile/order-tracking/{number}/orders`. An empty list is the app's
+ * "there is no order in the system". Shops choose their own numbers, so two
+ * shops' orders can share one; the app then lists both, and the website asks
+ * for the recipient's phone digits. Neither can be told apart here.
+ */
+export declare function fivePostOrderId(payload: unknown, raw: string): string;
+/**
+ * One order: its details from `GET /v3/mobile/order-tracking/{number}/orders/{orderId}`
+ * and its status history. The details must carry both the number and the
+ * order's id. Their `orderStatus` is the status the app heads the order with,
+ * and decides the stage; it can be newer than the history's last row.
+ */
+export declare function parseFivePost(details: unknown, statuses: unknown, rawOrderId: string, raw: string): CarrierResult;

package/dist/carriers/5post/parser.js

@@ -0,0 +1,164 @@
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { lastMovement } from '../../core/result/pickup.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { fivePostStage, fivePostWording } from './status.js';
+export const PROVIDER = '5Post';
+// A short shop number can list a few dozen orders; an order or its history is a few kilobytes.
+export const FIVE_POST_MAX_BYTES = 1024 * 1024;
+// A shop's order number in letters and digits, of at least the three the app asks for.
+const NUMBER = /^(?=[A-Z]*\d)[A-Z0-9]{3,40}$/;
+const ORDER_ID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+const CODE = /^[A-Z][A-Z\d_]{0,79}$/;
+// The warehouse a row names: "Обрабатывается на складе РЦ Казань", "Покинул склад РЦ Казань".
+// "Покинул склад. Ожидайте поступления в пункт выдачи" names none.
+const WAREHOUSE = /^(?:Обрабатывается на складе|Покинул склад)\s+([^\s.].*)$/u;
+const WAREHOUSE_CODES = new Set(['WAREHOUSE_PROCESSING', 'READY_FOR_SHIPMENT']);
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/**
+ * A 5Post number is the order number the shop gave the parcel, which 5Post
+ * matches whole and in upper case. Anything but letters and digits is not one.
+ */
+export function normalizeFivePostNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, '5Post numbers are a shop\'s order number of three or more letters and digits');
+    return number;
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 300) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `5Post returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+const sameNumber = (value, number) => typeof value === 'string' && value.trim().toUpperCase() === number;
+/**
+ * The order 5Post lists under the whole number, from the reply of
+ * `GET /v3/mobile/order-tracking/{number}/orders`. An empty list is the app's
+ * "there is no order in the system". Shops choose their own numbers, so two
+ * shops' orders can share one; the app then lists both, and the website asks
+ * for the recipient's phone digits. Neither can be told apart here.
+ */
+export function fivePostOrderId(payload, raw) {
+    const number = normalizeFivePostNumber(raw);
+    if (!Array.isArray(payload))
+        throw new SchemaError(PROVIDER, '5Post returned a reply without its order list');
+    if (!payload.length)
+        throw new NotFoundError(PROVIDER);
+    const ids = new Set();
+    for (const order of payload) {
+        if (!isRecord(order) || typeof order.orderId !== 'string' || !ORDER_ID.test(order.orderId)) {
+            throw new SchemaError(PROVIDER, '5Post returned an invalid order');
+        }
+        if (sameNumber(order.clientOrderId, number))
+            ids.add(order.orderId.toLowerCase());
+    }
+    if (!ids.size)
+        throw new IndeterminateError(PROVIDER, '5Post answered for another shipment');
+    if (ids.size > 1)
+        throw new IndeterminateError(PROVIDER, '5Post holds several orders under this number');
+    return [...ids][0];
+}
+/**
+ * The status history of `GET /v3/mobile/orders/{orderId}/status-history`,
+ * oldest first. Every row has an instant with its offset. 5Post's own rows
+ * (`primaryStatus`) carry the order's id; the customs broker's do not, and can
+ * carry the broker's contacts, which are not kept, nor are location ids.
+ */
+function history(payload, orderId) {
+    if (!Array.isArray(payload) || payload.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, '5Post returned an invalid status history');
+    const seen = new Set();
+    const rows = [];
+    payload.forEach((row, index) => {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, '5Post returned an invalid status');
+        // 5Post's own rows carry the order's id; the customs broker's rows come without one.
+        if (row.id === undefined && row.primaryStatus === true)
+            throw new SchemaError(PROVIDER, '5Post returned a status without its order');
+        if (row.id !== undefined && (typeof row.id !== 'string' || row.id.toLowerCase() !== orderId)) {
+            throw new IndeterminateError(PROVIDER, '5Post answered for another shipment');
+        }
+        const code = text(row, 'status', 80);
+        const at = explicitOffsetTime(row.changeDate);
+        if (!CODE.test(code) || !at)
+            throw new SchemaError(PROVIDER, '5Post returned a status without a code or clock');
+        const description = text(row, 'statusLocalized') || fivePostWording(code) || code;
+        const location = WAREHOUSE_CODES.has(code) ? WAREHOUSE.exec(description)?.[1]?.trim() : undefined;
+        const staged = fivePostStage(code, description);
+        const event = {
+            time: at.iso,
+            ...(location ? { location } : {}),
+            description,
+            ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+            provider_code: code,
+        };
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        rows.push({ event, at: at.timestamp, index });
+    });
+    // Newest first; of two rows at one instant, the later in the reply is newer.
+    return rows.sort((left, right) => right.at - left.at || right.index - left.index).map((row) => row.event);
+}
+/**
+ * The point the parcel waits at, or was collected from: its name and address
+ * from the order's details. Only a pickup point or locker is named, never a
+ * door the parcel goes to.
+ */
+function pickupPoint(details) {
+    const info = isRecord(details.locationInfo) ? details.locationInfo : null;
+    const receiver = info && isRecord(info.receiver) ? info.receiver : null;
+    if (!receiver || receiver.type !== 'PICKUP_POINT')
+        return '';
+    return [text(receiver, 'name', 160), text(receiver, 'address', 300)].filter(Boolean).join('\n');
+}
+/**
+ * One order: its details from `GET /v3/mobile/order-tracking/{number}/orders/{orderId}`
+ * and its status history. The details must carry both the number and the
+ * order's id. Their `orderStatus` is the status the app heads the order with,
+ * and decides the stage; it can be newer than the history's last row.
+ */
+export function parseFivePost(details, statuses, rawOrderId, raw) {
+    const number = normalizeFivePostNumber(raw);
+    const orderId = rawOrderId.toLowerCase();
+    if (!isRecord(details))
+        throw new SchemaError(PROVIDER, '5Post returned invalid order details');
+    if (typeof details.orderId !== 'string' || details.orderId.toLowerCase() !== orderId || !sameNumber(details.clientOrderId, number)) {
+        throw new IndeterminateError(PROVIDER, '5Post answered for another shipment');
+    }
+    const status = text(details, 'orderStatus', 80);
+    if (!CODE.test(status))
+        throw new SchemaError(PROVIDER, '5Post returned an order without its status');
+    const events = history(statuses, orderId);
+    const wording = events.find((event) => event.provider_code === status)?.description ?? fivePostWording(status) ?? status;
+    const current = fivePostStage(status, wording);
+    const stage = current?.stage;
+    const assigned = explicitOffsetTime(details.orderStatusAssignmentDate);
+    const newest = events[0] ? explicitOffsetTime(events[0].time) : null;
+    const updated = assigned && (!newest || assigned.timestamp > newest.timestamp) ? assigned : newest;
+    const delivered = stage === 'delivered' ? events.find((event) => event.stage === 'delivered') : undefined;
+    const deliveredAt = delivered?.time ?? (stage === 'delivered' ? assigned?.iso : undefined);
+    const collected = delivered !== undefined && lastMovement(events.slice(events.indexOf(delivered) + 1)) === 'ready_for_pickup';
+    const point = stage === 'ready_for_pickup' || collected ? pickupPoint(details) : '';
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(current ? { current_stage: current.stage, current_stage_source: current.source } : {}),
+        last_status_text: wording,
+        ...(events.length ? {} : { provider_code: status, summary_only: true }),
+        last_update: updated?.iso ?? null,
+        expected_delivery: null,
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        ...(point ? { pickup_point: point } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/5post/status.d.ts

@@ -0,0 +1,9 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage the map gives a status code. */
+export declare function fivePostMappedStage(code: string): Stage | undefined;
+/** How the app words a status code, when the map knows it. */
+export declare function fivePostWording(code: string): string | undefined;
+/** A status's stage: its code, else the shared wording rules for a code the map does not know, else nothing. */
+export declare function fivePostStage(code: string, wording: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/5post/status.js

@@ -0,0 +1,100 @@
+import { classifyWording } from '../../core/status/index.js';
+/**
+ * The order statuses of 5Post's app, as its `GET /v3/mobile/order-statuses`
+ * words them. A history row names the warehouse in the wording of
+ * WAREHOUSE_PROCESSING and READY_FOR_SHIPMENT, such as "Покинул склад РЦ …".
+ * An uncollected parcel's statuses start with "Не востребован" and a
+ * cancelled order's with "Отменён"; such a parcel is on its way back, though
+ * one taken from its pickup point can still be sent to another point.
+ */
+const CODES = new Map([
+    ['INFORMATION_RECEIVED', ['registered', 'Ожидается передача заказа в 5post']],
+    ['INCEPTION_PROBLEM', ['exception', 'Проблема']],
+    ['PROCESS_WITHDRAWN', ['accepted', 'Передан службе доставки']], // The sender left the parcel at a pickup point.
+    ['WAREHOUSE_PROCESSING', ['in_transit', 'Обрабатывается на складе']],
+    ['READY_FOR_SHIPMENT', ['in_transit', 'Покинул склад']],
+    ['DELIVERED', ['ready_for_pickup', 'Доставлен в пункт выдачи']], // Waiting at the pickup point or locker.
+    ['DONE', ['delivered', 'Получен']],
+    ['UNCLAIMED_APPROVED', ['returned', 'Не востребован. Ожидается передача заказа в 5post']],
+    ['UNCLAIMED_TRANSFERRED_TO_DELIVERY_SERVICE', ['returned', 'Не востребован. Передан службе доставки']],
+    ['UNCLAIMED_RECEIVED_IN_WAREHOUSE', ['returned', 'Не востребован. Обрабатывается на складе']],
+    ['UNCLAIMED_SHIPPED', ['returned', 'Не востребован. Покинул склад']],
+    ['UNCLAIMED_RETURN_TO_PARTNER', ['returned', 'Возвращен партнеру']],
+    ['UNCLAIMED_PLACED_IN_POSTAMAT', ['returned', 'Не востребован. Доставлен в пункт выдачи']], // At a point for the sender.
+    ['UNCLAIMED_READY_FOR_REPICKUP', ['in_transit', 'Готов к повторной доставке']], // To be sent to a pickup point again.
+    ['UNCLAIMED_RECEIVED_IN_COURIER_WAREHOUSE', ['returned', 'Не востребован. Обрабатывается на складе курьерской службы']],
+    ['UNCLAIMED_RETURNING_TO_PARTNER', ['returned', 'Не востребован. Возвращается отправителю']],
+    ['RETURNING_BY_EXPRESS_DELIVERY', ['returned', 'Не востребован. Возвращается курьерской службой']],
+    ['LOST', ['exception', 'Утерян']],
+    ['UTILIZED', ['exception', 'Утилизирован']],
+    ['CANCELLED', ['exception', 'Отменен']],
+    ['CANCELLED_APPROVED', ['exception', 'Отменён. Ожидается передача заказа в 5post']], // Cancelled before 5Post had it.
+    ['CANCELLED_TRANSFERRED_TO_DELIVERY_SERVICE', ['returned', 'Отменён. Передан службе доставки']],
+    ['CANCELLED_SHIPPED', ['returned', 'Отменён. Покинул склад']],
+    ['CANCELLED_RECEIVED_IN_WAREHOUSE', ['returned', 'Отменён. Обрабатывается на складе']],
+    ['CANCELLED_PLACED_IN_POSTAMAT', ['returned', 'Отменён. Доставлен в пункт выдачи']],
+    ['CANCELLED_RETURNING_BY_COURIER', ['returned', 'Отменен. Возвращается курьером']],
+    ['CANCELLED_RETURNING_TO_PARTNER', ['returned', 'Отменен. Возвращается отправителю']],
+    ['CANCELLED_IN_INTERNATIONAL_TRANSIT', ['exception', 'Отменён. Обратитесь к продавцу']],
+    ['RETURNED_TO_PARTNER', ['returned', 'Отправлен в интернет-магазин']],
+    ['RETURNED_TO_CLIENT', ['returned', 'Возвращен отправителю']],
+    ['REGISTRATION_ERROR_INCORRECT_PHONE_NUMBER', ['exception', 'Ошибка регистрации заказа: требуется уточнить номер телефона']],
+    ['REGISTRATION_ERROR_INCORRECT_DELIVERY_DATE', ['exception', 'Ошибка регистрации заказа: требуется уточнить дату доставки']],
+    ['REGISTRATION_ERROR_INCORRECT_CLIENT_ADDRESS', ['exception', 'Ошибка регистрации заказа: требуется уточнить адрес доставки']],
+    // Courier delivery to the door.
+    ['EXPRESS_DELIVERY_PREPARATION', ['in_transit', 'Подготовка к передаче курьерской службе']],
+    ['RECEIVED_BY_EXPRESS_DELIVERY', ['in_transit', 'Передан курьерской службе']],
+    ['RECEIVED_IN_COURIER_WAREHOUSE', ['in_transit', 'Обрабатывается на складе курьерской службы']],
+    ['RECEIVED_BY_COURIER', ['out_for_delivery', 'Передан курьеру']],
+    ['RETURNING_BY_COURIER', ['failed_attempt', 'Неуспешная попытка вручения']],
+    ['RECEIVED_IN_WAREHOUSE_AFTER_ATTEMPTED_DELIVERY', ['failed_attempt', 'Вернулся после неуспешной попытки доставки на склад партнера']],
+    // Parcels from abroad. The customs rows are the broker's, beside 5Post's own.
+    ['CUSTOMS_AWAITING_PAYMENT', ['customs', 'Требуется оплата таможенных платежей']],
+    ['CUSTOMS_CLEARANCE_STARTED', ['customs', 'Начато таможенное оформление']],
+    ['CUSTOMS_CLEARANCE_COMPLETED', ['in_transit', 'Таможенное оформление завершено']],
+    ['CUSTOMS_DATA_REQUIRED', ['customs', 'Требуется предоставить данные таможенному представителю']],
+    ['CUSTOMS_CLEARANCE_REJECTED', ['exception', 'Отказано таможней в выпуске']],
+    ['CUSTOMS_SENT_TO_COURIER', ['in_transit', 'Подготовлено к передаче 5post']],
+    ['CUSTOMS_RETURNED_TO_STORE', ['returned', 'Возврат в интернет-магазин']],
+    ['IN_INTERNATIONAL_TRANSIT_SHIPPED_FROM_WAREHOUSE', ['in_transit', 'В пути на таможню в стране отправления. Обычно занимает до 10 дней']],
+    ['IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_STARTED_ORIG', ['customs', 'Начато таможенное оформление в стране отправления']],
+    ['IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_COMPLETED', ['in_transit', 'Таможенное оформление завершено']],
+    ['IN_INTERNATIONAL_TRANSIT_LINEHAUL_TRANSIT_DEPARTURE', ['in_transit', 'Отправлен в страну назначения']],
+    ['IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_STARTED_DEST', ['customs', 'Начато таможенное оформление в стране назначения']],
+    ['IN_INTERNATIONAL_TRANSIT_DATA_REQUIRED', ['customs', 'Требуется предоставить данные таможенному представителю']],
+    ['IN_INTERNATIONAL_TRANSIT_READY_FOR_5POST', ['in_transit', 'Подготовлено к передаче 5post']],
+    ['RECEIVED_BY_AIR_CARRIER', ['in_transit', 'Передан авиаперевозчику']],
+    ['DEPARTED_BY_AIR', ['in_transit', 'Отправлен авиарейсом']],
+    ['DELIVERED_BY_AIR', ['in_transit', 'Доставлен авиарейсом']],
+    ['RETURNING_BY_AIR_CARRIER', ['returned', 'Возвращается авиаперевозчиком']],
+]);
+/** Statuses that say nothing about where the parcel is or how its journey ended. */
+const UNSTAGED = new Map([
+    ['UNDEFINED', 'В работе'],
+    ['COMPLETED_BY_PARTNER', 'Заказ перешел в терминальный статус на стороне партнера'],
+]);
+/** The stage the map gives a status code. */
+export function fivePostMappedStage(code) {
+    return CODES.get(code)?.[0];
+}
+/** How the app words a status code, when the map knows it. */
+export function fivePostWording(code) {
+    return CODES.get(code)?.[1] ?? UNSTAGED.get(code);
+}
+/** A status's stage: its code, else the shared wording rules for a code the map does not know, else nothing. */
+export function fivePostStage(code, wording) {
+    const mapped = fivePostMappedStage(code);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    if (UNSTAGED.has(code))
+        return null;
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+export const statusMap = {
+    stage: (code) => (code ? fivePostMappedStage(code) : undefined),
+    gaps: [
+        { code: 'UNDEFINED', note: '"В работе", in progress: an order status that says nothing of where the parcel is. One followed a loss in the history.' },
+        { code: 'COMPLETED_BY_PARTNER', note: 'The sender closed the order on its side, which does not say whether the parcel was delivered or went back.' },
+    ],
+};

package/dist/carriers/5post/statuses.json

@@ -15,9 +15,69 @@
     {"code": "READY_FOR_WITHDRAW_FROM_PICKUP_POINT", "wording": "Готов к изъятию из пункта выдачи", "stage": "returned", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen. The parcel was not collected and is due to be taken back from the pickup point."},
     {"code": "WITHDRAWN_FROM_PICKUP_POINT", "wording": "Изъят из пункта выдачи", "stage": "returned", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen. An uncollected parcel was taken back from the pickup point."},
     {"code": "WAITING_FOR_REPICKUP", "wording": "Ожидает повторную выдачу", "stage": "ready_for_pickup", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen."},
-    {"code": "LOST", "wording": "Утерян", "stage": "exception", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen."},
-    {"code": "CANCELLED", "wording": "Отменен", "stage": "exception", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen."},
     {"code": "RETURNED_TO_PARTNER", "wording": "Отгружен партнеру", "stage": "returned", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen. Handed back to the sending merchant."},
-    {"code": "UNCLAIMED", "wording": "Не востребован", "stage": "returned", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen. A main order status: the recipient never collected the parcel."}
+    {"code": "UNCLAIMED", "wording": "Не востребован", "stage": "returned", "language": "ru", "confirmedBy": "source", "note": "Label an open-source 5Post API client gives this API status; the public tracker's own wording was not seen. A main order status: the recipient never collected the parcel."},
+    {"code": "UNDEFINED", "wording": "В работе", "unmapped": true, "language": "ru", "confirmedBy": "live", "note": "\"In progress\": an order status that says nothing of where the parcel is. One order had it as its status long after its history reported a loss."},
+    {"code": "INFORMATION_RECEIVED", "wording": "Ожидается передача заказа в 5post", "stage": "registered", "language": "ru", "confirmedBy": "live", "note": "The sender registered the order; 5Post does not have the parcel yet."},
+    {"code": "INCEPTION_PROBLEM", "wording": "Проблема", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "A problem with the order. Seen just before a loss, and before an order was registered again."},
+    {"code": "WAREHOUSE_PROCESSING", "wording": "Обрабатывается на складе", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "At a 5Post warehouse; the history's wording names it."},
+    {"code": "READY_FOR_SHIPMENT", "wording": "Покинул склад", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "Left a warehouse; the history's wording names it, or says the parcel is on its way to the pickup point."},
+    {"code": "DELIVERED", "wording": "Доставлен в пункт выдачи", "stage": "ready_for_pickup", "language": "ru", "confirmedBy": "live", "note": "Arrived at the pickup point or locker and waits there for the recipient until the order's storage deadline."},
+    {"code": "DONE", "wording": "Получен", "stage": "delivered", "language": "ru", "confirmedBy": "live", "note": "Collected by the recipient."},
+    {"code": "UNCLAIMED_APPROVED", "wording": "Не востребован. Ожидается передача заказа в 5post", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UNCLAIMED_TRANSFERRED_TO_DELIVERY_SERVICE", "wording": "Не востребован. Передан службе доставки", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "Not collected by the storage deadline and taken from the pickup point. One such parcel was later sent to a pickup point again and collected."},
+    {"code": "UNCLAIMED_RECEIVED_IN_WAREHOUSE", "wording": "Не востребован. Обрабатывается на складе", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "An uncollected parcel back at a warehouse."},
+    {"code": "UNCLAIMED_SHIPPED", "wording": "Не востребован. Покинул склад", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UNCLAIMED_RETURN_TO_PARTNER", "wording": "Возвращен партнеру", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UNCLAIMED_PLACED_IN_POSTAMAT", "wording": "Не востребован. Доставлен в пункт выдачи", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "An uncollected parcel at a pickup point for its sender to collect. In the status list the app loads; not seen in a history."},
+    {"code": "LOST", "wording": "Утерян", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "Reported lost. The same code and wording are the partner API's."},
+    {"code": "UNCLAIMED_READY_FOR_REPICKUP", "wording": "Готов к повторной доставке", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "An uncollected parcel to be sent to a pickup point again. In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED", "wording": "Отменен", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "The order was cancelled. The same code and wording are the partner API's. In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_APPROVED", "wording": "Отменён. Ожидается передача заказа в 5post", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "The order was cancelled before 5Post had the parcel. In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_TRANSFERRED_TO_DELIVERY_SERVICE", "wording": "Отменён. Передан службе доставки", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_SHIPPED", "wording": "Отменён. Покинул склад", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_RECEIVED_IN_WAREHOUSE", "wording": "Отменён. Обрабатывается на складе", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_PLACED_IN_POSTAMAT", "wording": "Отменён. Доставлен в пункт выдачи", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RETURNING_BY_EXPRESS_DELIVERY", "wording": "Не востребован. Возвращается курьерской службой", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RECEIVED_BY_EXPRESS_DELIVERY", "wording": "Передан курьерской службе", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "EXPRESS_DELIVERY_PREPARATION", "wording": "Подготовка к передаче курьерской службе", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "REGISTRATION_ERROR_INCORRECT_PHONE_NUMBER", "wording": "Ошибка регистрации заказа: требуется уточнить номер телефона", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "REGISTRATION_ERROR_INCORRECT_DELIVERY_DATE", "wording": "Ошибка регистрации заказа: требуется уточнить дату доставки", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "REGISTRATION_ERROR_INCORRECT_CLIENT_ADDRESS", "wording": "Ошибка регистрации заказа: требуется уточнить адрес доставки", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "PROCESS_WITHDRAWN", "wording": "Передан службе доставки", "stage": "accepted", "language": "ru", "confirmedBy": "live", "note": "The parcel was handed to 5Post, such as a parcel one person sends another left at a shop's till."},
+    {"code": "RETURNED_TO_PARTNER", "wording": "Отправлен в интернет-магазин", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RETURNED_TO_CLIENT", "wording": "Возвращен отправителю", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UTILIZED", "wording": "Утилизирован", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "Disposed of. In the status list the app loads; not seen in a history."},
+    {"code": "CUSTOMS_AWAITING_PAYMENT", "wording": "Требуется оплата таможенных платежей", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CUSTOMS_CLEARANCE_STARTED", "wording": "Начато таможенное оформление", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "A customs broker's row for a parcel from abroad."},
+    {"code": "CUSTOMS_CLEARANCE_COMPLETED", "wording": "Таможенное оформление завершено", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "A customs broker's row: the parcel was cleared and moves on."},
+    {"code": "CUSTOMS_DATA_REQUIRED", "wording": "Требуется предоставить данные таможенному представителю", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CUSTOMS_CLEARANCE_REJECTED", "wording": "Отказано таможней в выпуске", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CUSTOMS_SENT_TO_COURIER", "wording": "Подготовлено к передаче 5post", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "A customs broker's row: the cleared parcel is to be handed to 5Post."},
+    {"code": "CUSTOMS_RETURNED_TO_STORE", "wording": "Возврат в интернет-магазин", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RECEIVED_IN_COURIER_WAREHOUSE", "wording": "Обрабатывается на складе курьерской службы", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RECEIVED_BY_COURIER", "wording": "Передан курьеру", "stage": "out_for_delivery", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RETURNING_BY_COURIER", "wording": "Неуспешная попытка вручения", "stage": "failed_attempt", "language": "ru", "confirmedBy": "live", "note": "A courier's failed attempt to deliver to the door. In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_RETURNING_BY_COURIER", "wording": "Отменен. Возвращается курьером", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_RETURNING_TO_PARTNER", "wording": "Отменен. Возвращается отправителю", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UNCLAIMED_RECEIVED_IN_COURIER_WAREHOUSE", "wording": "Не востребован. Обрабатывается на складе курьерской службы", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "UNCLAIMED_RETURNING_TO_PARTNER", "wording": "Не востребован. Возвращается отправителю", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_SHIPPED_FROM_WAREHOUSE", "wording": "В пути на таможню в стране отправления. Обычно занимает до 10 дней", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "CANCELLED_IN_INTERNATIONAL_TRANSIT", "wording": "Отменён. Обратитесь к продавцу", "stage": "exception", "language": "ru", "confirmedBy": "live", "note": "Cancelled on its way from abroad; the recipient is told to ask the seller. In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_STARTED_ORIG", "wording": "Начато таможенное оформление в стране отправления", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_COMPLETED", "wording": "Таможенное оформление завершено", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_LINEHAUL_TRANSIT_DEPARTURE", "wording": "Отправлен в страну назначения", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_CUSTOMS_CLEARANCE_STARTED_DEST", "wording": "Начато таможенное оформление в стране назначения", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_DATA_REQUIRED", "wording": "Требуется предоставить данные таможенному представителю", "stage": "customs", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "IN_INTERNATIONAL_TRANSIT_READY_FOR_5POST", "wording": "Подготовлено к передаче 5post", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "COMPLETED_BY_PARTNER", "wording": "Заказ перешел в терминальный статус на стороне партнера", "unmapped": true, "language": "ru", "confirmedBy": "live", "note": "The sender closed the order on its side, which does not say whether the parcel was delivered or went back. In the status list the app loads; not seen in a history."},
+    {"code": "RECEIVED_IN_WAREHOUSE_AFTER_ATTEMPTED_DELIVERY", "wording": "Вернулся после неуспешной попытки доставки на склад партнера", "stage": "failed_attempt", "language": "ru", "confirmedBy": "live", "note": "Back at the sender's warehouse after a failed delivery to the door. In the status list the app loads; not seen in a history."},
+    {"code": "RECEIVED_BY_AIR_CARRIER", "wording": "Передан авиаперевозчику", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "DEPARTED_BY_AIR", "wording": "Отправлен авиарейсом", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "DELIVERED_BY_AIR", "wording": "Доставлен авиарейсом", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "RETURNING_BY_AIR_CARRIER", "wording": "Возвращается авиаперевозчиком", "stage": "returned", "language": "ru", "confirmedBy": "live", "note": "In the status list the app loads; not seen in a history."},
+    {"code": "WAREHOUSE_PROCESSING", "wording": "Обрабатывается на складе РЦ Самара", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "The warehouse rows name the distribution centre (РЦ) or hub (ХАБ)."},
+    {"code": "READY_FOR_SHIPMENT", "wording": "Покинул склад РЦ Кстово", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "Left the named distribution centre."},
+    {"code": "READY_FOR_SHIPMENT", "wording": "Покинул склад. Ожидайте поступления в пункт выдачи", "stage": "in_transit", "language": "ru", "confirmedBy": "live", "note": "Left the last warehouse for the pickup point."}
   ]
 }

package/dist/carriers/ems-vietnam/adapter.d.ts

@@ -0,0 +1,17 @@
+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 the tracking page on ems.com.vn makes for the number typed in. */
+export declare const EMS_VIETNAM_API = "https://api.myems.vn/TrackAndTraceItemCode";
+/** The address the page asks: the number with `EMS` after it, and the Vietnamese wording. */
+export declare function emsVietnamLookupUrl(number: string): string;
+export declare class EmsVietnamTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;