universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/nacex/parser.js

@@ -0,0 +1,119 @@
+import { load } from 'cheerio';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/index.js';
+import { classifyNacexStatus } from './status.js';
+const NO_HISTORY = 'No existe ningún albarán introducido en el sistema cumpliendo los criterios especificados. Consulte con su agencia NACEX más cercana.';
+export function normalizeNacexNumber(raw) {
+    const number = raw.replace(/\s/g, '');
+    if (!/^\d{4}\/\d{8}$/.test(number))
+        throw new TypeError('NACEX requires an agency and eight-digit shipment number');
+    return number;
+}
+export function validateNacexBootstrap(html) {
+    const $ = load(html);
+    const form = $('form[name="seguimientoFormulario"]');
+    let action;
+    try {
+        action = new URL(form.attr('action') ?? '', 'https://www.nacex.es');
+    }
+    catch {
+        throw new SchemaError('NACEX', 'NACEX tracking form changed');
+    }
+    if (form.length !== 1 || form.attr('method')?.toLowerCase() !== 'post'
+        || action.origin !== 'https://www.nacex.es' || action.search || action.hash
+        || action.pathname.replace(/;jsessionid=[A-Za-z0-9._:-]{1,256}$/, '') !== '/seguimientoFormulario.do'
+        || form.find('input[name="agencia_origen"]').length !== 1
+        || form.find('input[name="numero_albaran"]').length !== 1) {
+        throw new SchemaError('NACEX', 'NACEX tracking form changed');
+    }
+}
+export function parseNacex(html, raw) {
+    const number = normalizeNacexNumber(raw);
+    const [agency, albaran] = number.split('/');
+    const $ = load(html);
+    const summary = $('#tabla_estado');
+    const history = $('#table_historico');
+    if (!summary.length && !history.length) {
+        const negative = $('.Z3 .t9').clone();
+        negative.find('br').replaceWith(' ');
+        // This is a scoped result of the submitted anonymous form, not a generic
+        // HTTP error or a hidden no-results message in the initial form.
+        if ($('.Z3 h2').length === 1 && clean($('.Z3 h2').text(), 80) === 'Formulario de Seguimiento'
+            && negative.length === 1 && clean(negative.text(), 300) === NO_HISTORY) {
+            throw new NotFoundError('NACEX');
+        }
+        throw new IndeterminateError('NACEX', 'NACEX did not return shipment history');
+    }
+    if (summary.length !== 1 || history.length !== 1)
+        throw new SchemaError('NACEX', 'NACEX returned ambiguous shipment history');
+    const summaryRows = summary.find('tr');
+    const identity = summaryRows.eq(0).children('td');
+    const statusCells = summaryRows.eq(1).children('td');
+    if (identity.length !== 2 || clean(identity.eq(0).text(), 40) !== 'Envío:' || clean(identity.eq(1).text(), 40) !== number
+        || statusCells.length !== 2 || clean(statusCells.eq(0).text(), 40) !== 'Estado:') {
+        throw new SchemaError('NACEX', 'NACEX returned a different or incomplete shipment');
+    }
+    const metadata = $('#capa_detalle_no_loginado .fuente_label');
+    for (const [label, expected] of [['Agencia origen', agency], ['Nº Albarán', albaran]]) {
+        const values = metadata.filter((_, node) => clean($(node).text(), 40) === label).map((_, node) => {
+            const parent = $(node).parent().clone();
+            parent.children().remove();
+            return clean(parent.text(), 40);
+        }).get();
+        if (!values.length || values.length > 2 || values.some(value => value !== expected)) {
+            throw new SchemaError('NACEX', 'NACEX returned a different or ambiguous shipment detail');
+        }
+    }
+    const summaryLabel = clean(statusCells.eq(1).text(), 120);
+    if (!summaryLabel || !/^[\p{L}][\p{L}\s().-]{1,119}$/u.test(summaryLabel))
+        throw new SchemaError('NACEX', 'NACEX returned an invalid current status');
+    const rows = history.find('tr');
+    if (!rows.length)
+        throw new IndeterminateError('NACEX', 'NACEX returned empty shipment history');
+    if (rows.length > 500)
+        throw new SchemaError('NACEX', 'NACEX returned too many scans');
+    const events = [];
+    let dayText = '';
+    for (const row of rows.toArray()) {
+        const cells = $(row).children('td');
+        if (cells.length !== 1)
+            throw new SchemaError('NACEX', 'NACEX history columns changed');
+        const cell = cells.eq(0);
+        if (cell.hasClass('sg_hist_fecha')) {
+            if (cell.attr('colspan') !== '2')
+                throw new SchemaError('NACEX', 'NACEX history date layout changed');
+            dayText = clean(cell.text(), 64);
+            continue;
+        }
+        if (!cell.hasClass('sg_hist_desc'))
+            throw new SchemaError('NACEX', 'NACEX history scan layout changed');
+        const labels = cell.children('b, font.fuente_titulo_green');
+        // Comments, signatures and contact instructions follow this label as
+        // separate text nodes. A parenthetical agency is routing detail, not code.
+        const label = clean(labels.text(), 160).replace(/\s*\(\d{4}\)$/, '');
+        if (labels.length !== 1 || !/^[\p{L}][\p{L}\s.-]{1,119}$/u.test(label)) {
+            throw new SchemaError('NACEX', 'NACEX returned an invalid scan label');
+        }
+        const mapped = classifyNacexStatus(label);
+        const movement = mapped && ['accepted', 'in_transit', 'out_for_delivery', 'ready_for_pickup'].includes(mapped.stage);
+        const trailing = clean(cell.contents().filter((_, node) => node.type === 'text').map((_, node) => $(node).text()).get().join(' '), 300);
+        // The same trailing column holds a recipient after delivery. Only the
+        // observed depot/locality shape of a mapped movement scan is a location.
+        const locality = movement && /^\d{4}(?:-\d{1,3})?\s*-\s*([\p{L}][\p{L}\s.()-]{1,99})$/u.exec(trailing)?.[1];
+        events.push({ description: mapped?.status === 'delivered' ? 'Delivered' : label, provider_status: label,
+            ...(dayText ? { provider_time_text: dayText } : {}), ...(locality ? { location: locality } : {}),
+            ...(mapped ? { stage: mapped.stage } : {}) });
+    }
+    if (!events.length || !events.some(event => event.stage))
+        throw new IndeterminateError('NACEX', 'NACEX returned no actual tracking scans');
+    // Calendar headings have no scan clock or zone. Preserve provider order,
+    // including same-day repeated scans, without inventing midnight instants.
+    const mapped = classifyNacexStatus(summaryLabel);
+    const latestPhysical = events.find(event => event.stage);
+    if (mapped?.stage === 'delivered' && latestPhysical?.stage !== 'delivered') {
+        throw new SchemaError('NACEX', 'NACEX current status contradicts its latest shipment scan');
+    }
+    return { status: mapped?.status ?? 'unknown', ...(mapped ? { current_stage: mapped.stage } : {}),
+        last_status_text: mapped?.status === 'delivered' ? 'Delivered' : summaryLabel,
+        last_update: null, events: events.slice(0, 100) };
+}

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

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function classifyNacexStatus(label: string): ClassifiedStatus | undefined;

package/dist/carriers/nacex/status.js

@@ -0,0 +1,12 @@
+const labels = {
+    ACEPTADA: { status: 'in_transit', stage: 'accepted' },
+    'EN TRANSITO': { status: 'in_transit', stage: 'in_transit' },
+    'EN REPARTO': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'DISPONIBLE EN PUNTO NACEX': { status: 'in_transit', stage: 'ready_for_pickup' },
+    AUSENTE: { status: 'exception', stage: 'failed_attempt' },
+    ENTREGADO: { status: 'delivered', stage: 'delivered' },
+};
+export function classifyNacexStatus(label) {
+    const key = label.normalize('NFD').replace(/\p{Diacritic}/gu, '').toUpperCase().trim();
+    return Object.hasOwn(labels, key) ? labels[key] : undefined;
+}

package/dist/carriers/nacex/statuses.json

@@ -0,0 +1,11 @@
+{
+  "carrier": "nacex",
+  "entries": [
+    { "wording": "Aceptada", "language": "es", "stage": "accepted", "confirmedBy": "live" },
+    { "wording": "En tránsito", "language": "es", "stage": "in_transit", "confirmedBy": "live" },
+    { "wording": "En reparto", "language": "es", "stage": "out_for_delivery", "confirmedBy": "live" },
+    { "wording": "Disponible en punto NACEX", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "live" },
+    { "wording": "Ausente", "language": "es", "stage": "failed_attempt", "confirmedBy": "live" },
+    { "wording": "Entregado", "language": "es", "stage": "delivered", "confirmedBy": "live" }
+  ]
+}

package/dist/carriers/ninja-van/adapter.d.ts

@@ -0,0 +1,11 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class NinjaVanTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/ninja-van/adapter.js

@@ -0,0 +1,45 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { BudgetExceededError, IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { normalizeNinjaVanNumber, parseNinjaVan, parseNinjaVanNotFound } from './parser.js';
+const ENDPOINT = 'https://walrus.ninjavan.co/my/dash/1.2/public/orders';
+export class NinjaVanTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeNinjaVanNumber(raw);
+        return runSteps({ carrier: 'ninja-van', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    signal.throwIfAborted();
+                    if (remainingMs <= 0)
+                        throw new BudgetExceededError('Ninja Van', context.budgetMs ?? 15_000);
+                    const url = new URL(ENDPOINT);
+                    url.searchParams.set('tracking_id', number);
+                    const { response, bytes } = await fetchBounded(url, { signal, headers: { Accept: 'application/json' } }, {
+                        provider: 'Ninja Van', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
+                        allowHttpStatuses: [404], fetcher: this.options.fetcher,
+                    });
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'Ninja Van');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('Ninja Van', 'Ninja Van returned invalid tracking JSON', { cause });
+                    }
+                    if (response.status === 404)
+                        return parseNinjaVanNotFound(payload, number);
+                    if (response.status !== 200)
+                        throw new IndeterminateError('Ninja Van', 'Ninja Van returned an inconclusive tracking response');
+                    return parseNinjaVan(payload, number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new NinjaVanTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'ninja-van', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeNinjaVanNumber(number))) };
+};

package/dist/carriers/ninja-van/carrier.json

@@ -0,0 +1,79 @@
+{
+  "id": "ninja-van",
+  "displayName": "Ninja Van",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "SG",
+      "MY",
+      "PH",
+      "ID",
+      "TH",
+      "VN"
+    ]
+  },
+  "brand": {
+    "color": "#ed2d26"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ninja-van",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 28
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.ninjavan.co/en-my/tracking?id={trackingNumber}",
+    "canaryUrl": "https://www.ninjavan.co/en-my/tracking",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "delivered_at"
+    ],
+    "discarded": [
+      "internal_events",
+      "inactive_estimates",
+      "shipper_details"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "ninjavan.co"
+      ],
+      "params": [
+        "id"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "ninja-van-1",
+      "pattern": "^NL(?:MY|SG|ID|PH|TH|VN)[A-Z]{1,2}\\d{8,10}$",
+      "confidence": "high"
+    },
+    {
+      "id": "ninja-van-2",
+      "pattern": "^NV(?:SG|MY|PH|ID|TH|VN)[A-Z0-9]{8,20}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/ninja-van/numbers.json

@@ -0,0 +1,67 @@
+{
+  "carrier": "ninja-van",
+  "records": [
+    {
+      "number": "DX149431",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://api-docs.ninjavan.co/"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "gls-ch",
+          "gls-fr",
+          "gls-de"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to Ninja Van, which no rule claims."
+    },
+    {
+      "number": "NLIDAP8003114210",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://mediakonsumen.com/2026/02/10/surat-pembaca/21-pesanan-lazada-berisi-ponsel-hilang-dalam-pengiriman-karena-permainan-jasa-kirim-mengganti-isi-paket-dan-sampai-pembeli-tidak-sesuai",
+        "date": "2026-02-10"
+      },
+      "expect": {
+        "carrier": "ninja-van",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Indonesian parcel (Ninja Xpress)."
+    },
+    {
+      "number": "NLMYA71943214",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/69db93b2876e4c3ccfc16628",
+        "date": "2026-04-12"
+      },
+      "expect": {
+        "carrier": "ninja-van",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Malaysian parcel."
+    },
+    {
+      "number": "NVSGBEDBP03784ADPL",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://api-docs.ninjavan.co/"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "ninja-van"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to Ninja Van, which stays one candidate among several."
+    }
+  ]
+}

package/dist/carriers/ninja-van/parser.d.ts

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+/** The MY public order endpoint is the only country route with a live positive. */
+export declare function normalizeNinjaVanNumber(raw: string): string;
+export declare function parseNinjaVanNotFound(payload: unknown, number: string): never;
+export declare function parseNinjaVan(payload: unknown, rawNumber: string): CarrierResult;

package/dist/carriers/ninja-van/parser.js

@@ -0,0 +1,95 @@
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { HIDDEN_NINJA_EVENTS, ninjaVanStatus } from './status.js';
+const PROVIDER = 'Ninja Van';
+const MAX_SCANS = 500;
+const MAX_EVENTS = 100;
+/** The MY public order endpoint is the only country route with a live positive. */
+export function normalizeNinjaVanNumber(raw) {
+    const number = raw.trim().toUpperCase().replace(/[\s-]/g, '');
+    if (!/^NLMY[A-Z]{1,2}\d{8,10}$/.test(number))
+        throw new TypeError('Ninja Van direct tracking requires an NLMY parcel ID');
+    return number;
+}
+export function parseNinjaVanNotFound(payload, number) {
+    const requested = normalizeNinjaVanNumber(number);
+    if (isRecord(payload) && isRecord(payload.error) && payload.error.code === 150002
+        && payload.error.title === 'Not Found'
+        && payload.error.message === `order by tracking id ${requested} not found.`) {
+        throw new NotFoundError(PROVIDER);
+    }
+    throw new IndeterminateError(PROVIDER, 'Ninja Van returned an inconclusive tracking error');
+}
+function scanClock(raw) {
+    if (raw == null)
+        return {};
+    if (typeof raw !== 'string')
+        throw new SchemaError(PROVIDER, 'Ninja Van returned an invalid scan clock');
+    const label = clean(raw, 80);
+    if (!label)
+        return {};
+    // All observed scan clocks carry Z. Reject impossible offsets and retain
+    // malformed labels; an older valid clock must not date the current state.
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-](?:(?:0\d|1[0-3]):?[0-5]\d|14:?00))$/i.test(label)) {
+        const parsed = explicitOffsetTime(label);
+        if (parsed)
+            return { time: parsed.iso };
+    }
+    return { provider_time_text: label };
+}
+export function parseNinjaVan(payload, rawNumber) {
+    const number = normalizeNinjaVanNumber(rawNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER);
+    if (payload.error != null)
+        throw new IndeterminateError(PROVIDER, 'Ninja Van returned a tracking error');
+    if (payload.tracking_id !== number || typeof payload.id !== 'number' || !Number.isSafeInteger(payload.id)
+        || payload.id <= 0 || !Array.isArray(payload.events) || payload.events.length > MAX_SCANS
+        || typeof payload.status !== 'string' || typeof payload.granular_status !== 'string') {
+        throw new SchemaError(PROVIDER, 'Ninja Van returned a different or incomplete shipment');
+    }
+    if (!payload.events.length)
+        throw new IndeterminateError(PROVIDER, 'Ninja Van returned no parcel history');
+    // The official client reverses this oldest-first feed and hides three
+    // internal event types. That matters here: a routing row can follow a
+    // completed return, but is not a new delivery transition.
+    const events = [];
+    let returning = false;
+    for (const row of payload.events) {
+        if (!isRecord(row) || row.order_id !== payload.id || !isRecord(row.data)
+            || typeof row.type !== 'string' || !/^[A-Z][A-Z0-9_]{0,79}$/.test(row.type)) {
+            throw new SchemaError(PROVIDER, 'Ninja Van returned an invalid parcel scan');
+        }
+        if (row.data.is_rts != null && typeof row.data.is_rts !== 'boolean') {
+            throw new SchemaError(PROVIDER, 'Ninja Van returned an invalid return marker');
+        }
+        const clock = scanClock(row.time);
+        if (row.type === 'RTS' || row.data.is_rts === true)
+            returning = true;
+        if (HIDDEN_NINJA_EVENTS.has(row.type))
+            continue;
+        const mapped = ninjaVanStatus(row.type);
+        const completedReturn = row.type === 'DELIVERY_SUCCESS' && row.data.is_rts === true;
+        const ambiguousReturnDelivery = returning && row.type === 'DELIVERY_SUCCESS' && row.data.is_rts !== true;
+        const stage = completedReturn ? 'returned' : ambiguousReturnDelivery ? 'exception' : mapped?.stage;
+        const location = clean(row.data.hub_name, 160);
+        events.push({ provider_code: row.type, description: row.type.replaceAll('_', ' ').toLowerCase(), ...clock,
+            ...(location ? { location } : {}), ...(stage ? { stage } : {}), ...(returning ? { provider_leg: 'return' } : {}),
+        });
+    }
+    events.reverse();
+    if (!events.length)
+        throw new IndeterminateError(PROVIDER, 'Ninja Van returned no visible parcel history');
+    const latest = events[0];
+    const returned = latest.stage === 'returned';
+    const mapped = ninjaVanStatus(latest.provider_code ?? '');
+    const currentStage = latest.stage;
+    const status = returned ? 'exception' : currentStage === 'exception' ? 'exception' : mapped?.status ?? 'unknown';
+    return { status, ...(currentStage ? { current_stage: currentStage } : {}),
+        last_status_text: returned ? 'Returned to sender' : latest.description,
+        last_update: latest.time ?? null, expected_delivery: null,
+        ...(currentStage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        events: events.slice(0, MAX_EVENTS) };
+}

package/dist/carriers/ninja-van/status.d.ts

@@ -0,0 +1,3 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare const HIDDEN_NINJA_EVENTS: Set<string>;
+export declare function ninjaVanStatus(type: string): ClassifiedStatus | undefined;

package/dist/carriers/ninja-van/status.js

@@ -0,0 +1,25 @@
+// Public tracking events. The website omits its internal routing and shipment
+// bookkeeping rows from the visible timeline.
+export const HIDDEN_NINJA_EVENTS = new Set(['ADDED_TO_SHIPMENT', 'PARCEL_ROUTING_SCAN', 'FROM_DP_TO_DRIVER']);
+const STATES = {
+    RTS: { status: 'exception', stage: 'exception' },
+    DRIVER_PICKUP_SCAN: { status: 'in_transit', stage: 'in_transit' },
+    HUB_INBOUND_SCAN: { status: 'in_transit', stage: 'in_transit' },
+    DRIVER_INBOUND_SCAN: { status: 'in_transit', stage: 'in_transit' },
+    ARRIVED_AT_ORIGIN_HUB: { status: 'in_transit', stage: 'in_transit' },
+    ARRIVED_AT_TRANSIT_HUB: { status: 'in_transit', stage: 'in_transit' },
+    ARRIVED_AT_DESTINATION_HUB: { status: 'in_transit', stage: 'in_transit' },
+    ROUTE_INBOUND_SCAN: { status: 'in_transit', stage: 'in_transit' },
+    FROM_SHIPPER_TO_DP: { status: 'in_transit', stage: 'in_transit' },
+    FROM_DRIVER_TO_DP: { status: 'in_transit', stage: 'in_transit' },
+    FROM_DP_TO_CUSTOMER: { status: 'in_transit', stage: 'in_transit' },
+    DELIVERY_SUCCESS: { status: 'delivered', stage: 'delivered' },
+    DELIVERY_FAILURE: { status: 'exception', stage: 'failed_attempt' },
+    INACCURATE_ADDRESS: { status: 'exception', stage: 'exception' },
+    DAMAGE: { status: 'exception', stage: 'exception' },
+    LOST: { status: 'exception', stage: 'exception' },
+    CANCEL: { status: 'exception', stage: 'exception' },
+};
+export function ninjaVanStatus(type) {
+    return Object.hasOwn(STATES, type) ? STATES[type] : undefined;
+}

package/dist/carriers/ninja-van/statuses.json

@@ -0,0 +1,11 @@
+{
+  "carrier": "ninja-van",
+  "entries": [
+    { "code": "RTS", "wording": "RTS", "language": "en", "stage": "exception", "confirmedBy": "live" },
+    { "code": "DRIVER_PICKUP_SCAN", "wording": "DRIVER_PICKUP_SCAN", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "HUB_INBOUND_SCAN", "wording": "HUB_INBOUND_SCAN", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "ADDED_TO_SHIPMENT", "wording": "ADDED_TO_SHIPMENT", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "PARCEL_ROUTING_SCAN", "wording": "PARCEL_ROUTING_SCAN", "language": "en", "stage": "in_transit", "confirmedBy": "live" },
+    { "code": "DRIVER_INBOUND_SCAN", "wording": "DRIVER_INBOUND_SCAN", "language": "en", "stage": "in_transit", "confirmedBy": "live" }
+  ]
+}

package/dist/carriers/nz-post/adapter.d.ts

@@ -0,0 +1,11 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class NzPostTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

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

@@ -0,0 +1,45 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { normalizeNzPostNumber, parseNzPost } from './parser.js';
+const ENDPOINT = 'https://tools.nzpost.co.nz/tracking/api/parceltrack/parcels';
+export class NzPostTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeNzPostNumber(raw);
+        return runSteps({ carrier: 'nz-post', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    signal.throwIfAborted();
+                    const url = new URL(ENDPOINT);
+                    url.searchParams.set('tracking_reference', number);
+                    let bytes;
+                    try {
+                        ({ bytes } = await fetchBounded(url, { signal, headers: { Accept: 'application/json', 'Content-Type': 'application/json' } }, { provider: 'nz-post', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000, fetcher: this.options.fetcher }));
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                            throw new TransportError('nz-post', 'NZ Post tracking endpoint is unavailable', { cause: error });
+                        }
+                        throw error;
+                    }
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'nz-post');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('nz-post', 'NZ Post returned invalid tracking JSON', { cause });
+                    }
+                    return parseNzPost(payload, number);
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new NzPostTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'nz-post', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeNzPostNumber(number))) };
+};

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

@@ -0,0 +1,82 @@
+{
+  "id": "nz-post",
+  "displayName": "NZ Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "NZ"
+    ]
+  },
+  "brand": {
+    "color": "#d8291c"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "nz-post",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 32
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.nzpost.co.nz/tools/tracking?trackid={trackingNumber}",
+    "canaryUrl": "https://www.nzpost.co.nz/tools/tracking",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "delivery_controls",
+      "proof_of_delivery",
+      "delivered_at"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "delivered_at"
+    ],
+    "discarded": [
+      "recipient",
+      "signatures",
+      "delivery_descriptions",
+      "delivery_assets"
+    ],
+    "unavailable": [
+      "eta",
+      "delivery_controls"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "www.nzpost.co.nz"
+      ],
+      "params": [
+        "trackid"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "nz-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}NZ$",
+      "confidence": "high",
+      "checksum": "s10"
+    },
+    {
+      "id": "nz-post-2",
+      "pattern": "^\\d{20}$",
+      "confidence": "low"
+    }
+  ]
+}