universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/planzer/adapter.js

@@ -0,0 +1,148 @@
+import { SchemaError } from '../../core/errors/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { PlanzerSharedTracker } from './shared.js';
+import { PLANZER_STATUS, planzerDescription, planzerEventStage } from './status.js';
+const PROVIDER = 'Planzer';
+const UPSTREAM = 'Planzer tracking';
+const SHIPMENTS_URL = 'https://api.tracking.app.planzer.ch/api/v1/shipments';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const BASE_HEADERS = {
+    Accept: 'application/json, text/plain, */*',
+    'Accept-Language': 'en-US,en;q=0.9',
+    'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+};
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function recordArray(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function comparableIdentifier(value) {
+    return text(value).toLocaleUpperCase('en-US').replace(/[^A-Z0-9]/g, '');
+}
+/**
+ * The shipment number the API expects. Planzer prints `reference.shipment`
+ * composites (`87979.0061660090`); only the shipment half is looked up, without
+ * its leading zeros. The app stores numbers without dots, so a 5-digit
+ * reference followed by a zero-padded 10-digit shipment is split the same way.
+ */
+export function planzerShipmentNumber(trackingNumber) {
+    const raw = trackingNumber.includes('.')
+        ? trackingNumber.split('.', 2)[1] ?? ''
+        : /^\d{5}(0\d{9})$/.exec(trackingNumber)?.[1];
+    if (raw === undefined)
+        return trackingNumber;
+    return raw.replace(/^0+/, '') || raw;
+}
+// The parcels of one shipment repeat each milestone seconds or minutes apart.
+const SAME_MILESTONE_MS = 15 * 60_000;
+function eventMillis(time) {
+    // Naive local timestamps with up to seven fractional digits; only differences matter.
+    return Date.parse(`${time.slice(0, 19)}Z`);
+}
+/** One row per milestone the parcels share, at its first occurrence. */
+function mergeParcelMilestones(events) {
+    const kept = [];
+    for (const event of [...events].sort((left, right) => text(left.time).localeCompare(text(right.time)))) {
+        const at = eventMillis(text(event.time));
+        const repeated = kept.some((other) => other.description === event.description
+            && Math.abs(eventMillis(text(other.time)) - at) <= SAME_MILESTONE_MS);
+        if (!repeated)
+            kept.push(event);
+    }
+    return kept;
+}
+/** Projects one `/shipments/{shipment}/Pak` payload. Pure: the offline tests target this. */
+export function parsePlanzerTrackingResponse(value, shipmentNumber) {
+    const payload = record(value);
+    const overall = record(payload.overallStatus);
+    const statusText = text(record(overall.text).english);
+    if (!Array.isArray(payload.transportPositions)) {
+        throw new SchemaError(PROVIDER, 'Planzer returned an invalid shipment response');
+    }
+    const positions = recordArray(payload.transportPositions);
+    if (positions.length !== payload.transportPositions.length) {
+        throw new SchemaError(PROVIDER, 'Planzer returned an invalid transport position');
+    }
+    const requested = comparableIdentifier(shipmentNumber);
+    const identified = positions.filter((position) => comparableIdentifier(position.positionNumber));
+    if (identified.length === 0) {
+        throw new SchemaError(PROVIDER, 'Planzer did not return a shipment identifier');
+    }
+    const parcelPositions = identified.filter((position) => comparableIdentifier(position.positionNumber) === requested);
+    // Looked up by shipment number: every position belongs to the requested shipment.
+    const wholeShipment = parcelPositions.length === 0 && comparableIdentifier(payload.shipmentNumber) === requested;
+    const matchingPositions = wholeShipment ? identified : parcelPositions;
+    if (matchingPositions.length === 0) {
+        throw new SchemaError(PROVIDER, 'Planzer returned a different shipment');
+    }
+    let events = [];
+    for (const position of matchingPositions) {
+        for (const event of recordArray(position.positionEvents)) {
+            const description = text(record(event.text).english);
+            const stage = planzerEventStage(description);
+            if (!stage) {
+                // Surface schema changes through the existing sync error monitoring;
+                // never silently turn an unfamiliar historical event into a delivery.
+                throw new SchemaError('Planzer', 'Planzer returned an unrecognized tracking event status');
+            }
+            events.push({
+                time: text(event.createdAt),
+                location: '',
+                description: planzerDescription(description),
+                stage,
+            });
+        }
+    }
+    if (matchingPositions.length > 1)
+        events = mergeParcelMilestones(events);
+    events.sort((left, right) => text(right.time).localeCompare(text(left.time)));
+    return {
+        status: PLANZER_STATUS.get(statusText) ?? (statusText ? 'in_transit' : 'unknown'),
+        last_status_text: planzerDescription(statusText),
+        last_update: events[0]?.time || null,
+        expected_delivery: text(record(payload.deliveryDay).date) || null,
+        events,
+    };
+}
+export class PlanzerTracker {
+    fetcher;
+    timeoutMs;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async fetch(trackingNumber) {
+        const shipmentNumber = planzerShipmentNumber(trackingNumber);
+        const { bytes } = await fetchBounded(`${SHIPMENTS_URL}/${encodeURIComponent(shipmentNumber)}/Pak`, { headers: BASE_HEADERS }, {
+            provider: UPSTREAM,
+            timeoutMs: this.timeoutMs,
+            // One replay after a transport failure, HTTP 502/503/504, or a 429
+            // with a short Retry-After; parsing and validation are never retried.
+            retryTransient: true,
+            fetcher: this.fetcher,
+        });
+        return parsePlanzerTrackingResponse(parseJsonBytes(bytes, UPSTREAM), shipmentNumber);
+    }
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export async function fetchPlanzer(trackingNumber) {
+    return new PlanzerTracker().fetch(trackingNumber);
+}
+export const adapter = (environment) => {
+    const tracker = new PlanzerTracker({ fetcher: environment.fetcher });
+    const shared = new PlanzerSharedTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'planzer',
+        // Both routes are a single bounded request; the capability URL decides
+        // which one, not a fallback tier.
+        steps: ['direct'],
+        track: (input) => (input.trackingUrl
+            ? shared.fetch(input.number, input.trackingUrl)
+            : tracker.fetch(input.number)),
+    };
+};

package/dist/carriers/planzer/carrier.json

@@ -0,0 +1,85 @@
+{
+  "id": "planzer",
+  "displayName": "Planzer",
+  "aliases": [
+    "Planzer Group"
+  ],
+  "region": {
+    "countries": [
+      "CH"
+    ]
+  },
+  "brand": {
+    "color": "#e30613"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "planzer",
+    "upstreamName": "Planzer",
+    "requirements": [
+      {
+        "field": "trackingUrl",
+        "validator": "planzerSharedUrl",
+        "whenTrackingNumber": "^99990\\d{8}$",
+        "label": "Planzer tracking URL",
+        "type": "url",
+        "placeholder": "https://trackandtrace.planzergroup.com/shared/…",
+        "help": "Paste the complete shared link, including its accessKey."
+      }
+    ],
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://tracking.app.planzer.ch/delivery/info?deliveryNumber={trackingNumber}",
+    "canaryUrl": "https://tracking.app.planzer.ch/",
+    "shows": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "eta"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "trackandtrace.planzergroup.com"
+      ],
+      "path": "/shared/sendungen/([^/?#]+)",
+      "keepsCapabilityUrl": true
+    },
+    {
+      "domains": [
+        "tracking.app.planzer.ch"
+      ],
+      "params": [
+        "deliveryNumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "planzer-1",
+      "pattern": "^99990\\d{8}$",
+      "confidence": "high"
+    },
+    {
+      "id": "planzer-2",
+      "pattern": "^91346097\\d{12}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/planzer/numbers.json

@@ -0,0 +1,118 @@
+{
+  "carrier": "planzer",
+  "records": [
+    {
+      "number": "11652.0059554609",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a1ad21200205c065a1b7aa8",
+        "date": "2026-05-30"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "dpd-fr",
+          "yunda"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Planzer, which no rule claims. Printed as reference.shipment."
+    },
+    {
+      "number": "12345678",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/ha-parcel-integrations/ha-planzer/blob/main/README.md"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "mondial-relay",
+          "heppner"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Planzer, which no rule claims."
+    },
+    {
+      "number": "61214174",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a45580211a8ca65d11c1072",
+        "date": "2026-07-01"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "mondial-relay",
+          "heppner"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Planzer, which no rule claims. The 8-digit shipment number Planzer prints."
+    },
+    {
+      "number": "87979.0061660090",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a463a9fe1dee431b2338215",
+        "date": "2026-07-02"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "yunda"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Planzer, which no rule claims. Printed as reference.shipment."
+    },
+    {
+      "number": "91346097123456789012",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "planzer",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "98765.0012345678",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/ha-parcel-integrations/ha-planzer/blob/main/README.md"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "yunda"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Planzer, which no rule claims."
+    },
+    {
+      "number": "999.90.03316119",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "planzer",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    }
+  ]
+}

package/dist/carriers/planzer/shared.d.ts

@@ -0,0 +1,19 @@
+export { validatePlanzerSharedUrl } from '../../core/catalog/urls.js';
+import { isPlanzerSharedTrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export { isPlanzerSharedTrackingNumber, normalizeTrackingNumber };
+/**
+ * Accepts only a complete, https Planzer shared link for this very shipment,
+ * with exactly one well-formed access key. Returns the canonical URL to fetch.
+ */
+/** Projects one shared route page. Pure: the offline tests target this. */
+export declare function parsePlanzerTrackingHtml(html: string, trackingNumber: string): CarrierResult;
+export declare class PlanzerSharedTracker {
+    private readonly fetcher;
+    readonly timeoutMs: number;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(trackingNumber: string, trackingUrl: string): Promise<CarrierResult>;
+}

package/dist/carriers/planzer/shared.js

@@ -0,0 +1,135 @@
+import { validatePlanzerSharedUrl } from '../../core/catalog/urls.js';
+export { validatePlanzerSharedUrl } from '../../core/catalog/urls.js';
+/**
+ * Planzer shared shipments.
+ *
+ * A `999.90.########` shipment is not in the tracking API. Planzer publishes
+ * it as a capability link — `trackandtrace.planzergroup.com/shared/sendungen/
+ * {number}?accessKey=…` — which renders the five-step route page. The access
+ * key is part of the tracking credential and is validated before the lookup.
+ *
+ * The page carries no status code, so the route steps are read from the
+ * markup: their tooltip labels name the stage, `text-primary` marks the ones
+ * already reached, and the `<time datetime>` next to each carries its
+ * timestamp.
+ */
+import { load } from 'cheerio';
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { isPlanzerSharedTrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { decodeText, fetchBounded } from '../../core/transport/index.js';
+import { PLANZER_ROUTE_STAGES, PLANZER_ROUTE_STATUS, planzerRouteStage, } from './status.js';
+export { isPlanzerSharedTrackingNumber, normalizeTrackingNumber };
+const PROVIDER = 'Planzer';
+const UPSTREAM = 'Planzer shared tracking';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const EVENT_DESCRIPTIONS = {
+    registered: 'Shipment registered by Planzer',
+    accepted: 'Shipment accepted from the sender',
+    in_transit: 'Shipment at the transfer depot',
+    out_for_delivery: 'Out for delivery',
+    delivered: 'Delivered',
+};
+const NOT_FOUND_MESSAGES = new Set([
+    'keine sendungen gefunden.',
+    'aucun envoi trouve.',
+    'nessuna spedizione trovata.',
+    'no shipments found.',
+]);
+/**
+ * Accepts only a complete, https Planzer shared link for this very shipment,
+ * with exactly one well-formed access key. Returns the canonical URL to fetch.
+ */
+/** Projects one shared route page. Pure: the offline tests target this. */
+export function parsePlanzerTrackingHtml(html, trackingNumber) {
+    const $ = load(html);
+    const notice = $('p.lead').first().text().trim()
+        .toLocaleLowerCase()
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '');
+    const timestamps = $('time[datetime]').toArray()
+        .map((element) => ($(element).attr('datetime') ?? '').trim())
+        .filter(Boolean);
+    const steps = [];
+    $('div.text-center').each((_, element) => {
+        const container = $(element);
+        const target = container.find('span.tooltip-target').first();
+        if (target.length === 0)
+            return;
+        const label = (target.attr('data-original-title') ?? target.attr('title') ?? '').trim();
+        if (!label)
+            return;
+        steps.push({
+            label,
+            reached: target.hasClass('text-primary'),
+            timestamp: (container.find('time[datetime]').first().attr('datetime') ?? '').trim(),
+        });
+    });
+    const seen = new Set();
+    const uniqueSteps = steps.filter((step) => {
+        const key = step.label.toLocaleLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    if (uniqueSteps.length < PLANZER_ROUTE_STAGES.length) {
+        // A short page is only "unknown shipment" when Planzer says so; anything
+        // else (maintenance, a partial render) must stay an error.
+        if (NOT_FOUND_MESSAGES.has(notice))
+            throw new NotFoundError(PROVIDER);
+        throw new SchemaError(PROVIDER, 'Planzer returned an invalid tracking page');
+    }
+    const events = [];
+    let currentStage = null;
+    let currentLabel = '';
+    uniqueSteps.slice(0, PLANZER_ROUTE_STAGES.length).forEach((step, index) => {
+        const stage = planzerRouteStage(step.label) ?? PLANZER_ROUTE_STAGES[index];
+        if (!step.reached)
+            return;
+        currentStage = stage;
+        currentLabel = step.label || EVENT_DESCRIPTIONS[stage];
+        events.push({
+            time: step.timestamp,
+            location: '',
+            // The rendered label is the recipient's language; the retained
+            // description is our own neutral wording for the stage.
+            description: EVENT_DESCRIPTIONS[stage],
+        });
+    });
+    if (!currentStage) {
+        throw new SchemaError(PROVIDER, 'Planzer returned a shipment without a current stage');
+    }
+    const dates = [...new Set(timestamps.filter((timestamp) => /^\d{4}-\d{2}-\d{2}/.test(timestamp))
+            .map((timestamp) => timestamp.slice(0, 10)))].sort();
+    return {
+        status: PLANZER_ROUTE_STATUS[currentStage],
+        last_status_text: currentLabel,
+        last_update: events.at(-1)?.time || null,
+        expected_delivery: dates.at(-1) ?? null,
+        events: events.reverse(),
+        tracking_number: normalizeTrackingNumber(trackingNumber),
+    };
+}
+export class PlanzerSharedTracker {
+    fetcher;
+    timeoutMs;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async fetch(trackingNumber, trackingUrl) {
+        const url = validatePlanzerSharedUrl(trackingUrl, trackingNumber);
+        const { bytes } = await fetchBounded(url, {
+            headers: {
+                Accept: 'text/html,application/xhtml+xml',
+                'Accept-Language': 'de-CH,de;q=0.9,en;q=0.8',
+                'User-Agent': 'SwissDeliveryTracker/1.0',
+            },
+        }, {
+            provider: UPSTREAM,
+            timeoutMs: this.timeoutMs,
+            fetcher: this.fetcher,
+        });
+        return parsePlanzerTrackingHtml(decodeText(bytes), trackingNumber);
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Planzer (and Quickpac) status vocabulary.
+ *
+ * Two routes, two vocabularies:
+ *
+ * - The tracking API returns an English label per shipment and per milestone
+ *   (`overallStatus.text.english`, `positionEvents[].text.english`). Planzer's
+ *   English "Shipped" means "Zugestellt" / "Livré" — delivered, not dispatched
+ *   — so each milestone is classified on its own instead of inheriting the
+ *   shipment's current status, and that label is stored as "Delivered".
+ * - The shared capability page renders a five-step route whose step labels are
+ *   localized; `planzerRouteStage()` recognizes them by substring.
+ *
+ * An API label that is in neither map is an error rather than an unmapped
+ * event: the adapter refuses to turn unfamiliar wording into history.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../core/status/index.js';
+/** Shipment-level English labels from `overallStatus.text.english`. */
+export declare const PLANZER_STATUS: Map<string, CarrierStatus>;
+export declare const PLANZER_EVENT_STAGE: Map<string, "pending" | "registered" | "accepted" | "in_transit" | "out_for_delivery" | "delivered" | "customs" | "failed_attempt" | "ready_for_pickup" | "returned" | "exception">;
+/** The wording stored and shown for one English API label. */
+export declare function planzerDescription(label: string): string;
+export declare const PLANZER_TRANSLATED_EVENT_STAGE: Map<string, "pending" | "registered" | "accepted" | "in_transit" | "out_for_delivery" | "delivered" | "customs" | "failed_attempt" | "ready_for_pickup" | "returned" | "exception">;
+/** The milestone stage for one API label, or undefined when the label is unknown. */
+export declare function planzerEventStage(description: string): Stage | undefined;
+/** The five steps the shared capability page draws, in the order it draws them. */
+export declare const PLANZER_ROUTE_STAGES: readonly ["registered", "accepted", "in_transit", "out_for_delivery", "delivered"];
+export type PlanzerRouteStage = (typeof PLANZER_ROUTE_STAGES)[number];
+/** The route stage a shared-page step label names, or null when it names none. */
+export declare function planzerRouteStage(label: string): PlanzerRouteStage | null;
+/** The shipment status a reached route stage implies. */
+export declare const PLANZER_ROUTE_STATUS: Record<PlanzerRouteStage, CarrierStatus>;

package/dist/carriers/planzer/status.js

@@ -0,0 +1,89 @@
+/** Shipment-level English labels from `overallStatus.text.english`. */
+export const PLANZER_STATUS = new Map([
+    ['Recorded', 'pending'],
+    ['Transferred', 'in_transit'],
+    ['Shipment on the way', 'in_transit'],
+    ['In delivery', 'out_for_delivery'],
+    ['Shipment out for delivery', 'out_for_delivery'],
+    ['Delivered', 'delivered'],
+    ['Shipment delivered', 'delivered'],
+    ['Shipped', 'delivered'],
+    ['Not delivered', 'exception'],
+    ['Not delivered – A delivery card has been deposited', 'exception'],
+    ['New delivery released', 'in_transit'],
+]);
+// Classify each milestone independently of the shipment's current status.
+// Planzer's English "Shipped" means "Zugestellt" / "Livré", not dispatched.
+export const PLANZER_EVENT_STAGE = new Map([
+    ['Recorded', 'registered'],
+    ['Transferred', 'in_transit'],
+    ['Shipment on the way', 'in_transit'],
+    ['In delivery', 'out_for_delivery'],
+    ['Shipment out for delivery', 'out_for_delivery'],
+    ['Delivered', 'delivered'],
+    ['Shipment delivered', 'delivered'],
+    ['Shipped', 'delivered'],
+    ['Not delivered', 'failed_attempt'],
+    ['Not delivered – A delivery card has been deposited', 'failed_attempt'],
+    // "Erneute Zustellung ausgelöst": a redelivery was booked after a failed attempt.
+    ['New delivery released', 'in_transit'],
+]);
+// Planzer's English labels are translations of its German ones, and
+// "Zugestellt" came out as "Shipped" (the same event reads "Livré" and
+// "Consegnato", and the shipment summary says "Shipment delivered"). Such a
+// label is classified as received but stored in the wording it means; every
+// other label is kept verbatim. Event identities hash the stored wording, so
+// changing an entry here needs a migration for the rows already saved.
+const PLANZER_WORDING = new Map([
+    ['Shipped', 'Delivered'],
+]);
+/** The wording stored and shown for one English API label. */
+export function planzerDescription(label) {
+    return PLANZER_WORDING.get(label) ?? label;
+}
+// GENERATED localization aliases, kept separate from the observed English API
+// labels above. Prefer a future observed label/code if it contradicts an alias.
+// Livré/Zugestellt are semantic equivalents of Planzer's unusual Shipped label;
+// Expédié/Versandt/Spedito are intentionally absent.
+export const PLANZER_TRANSLATED_EVENT_STAGE = new Map([
+    ['enregistré', 'registered'], ['erfasst', 'registered'], ['registrato', 'registered'],
+    ['transféré', 'in_transit'], ['weitergeleitet', 'in_transit'], ['inoltrato', 'in_transit'],
+    ['en cours de livraison', 'out_for_delivery'], ['in zustellung', 'out_for_delivery'], ['in consegna', 'out_for_delivery'],
+    ['livré', 'delivered'], ['zugestellt', 'delivered'], ['consegnato', 'delivered'],
+]);
+/** The milestone stage for one API label, or undefined when the label is unknown. */
+export function planzerEventStage(description) {
+    return PLANZER_EVENT_STAGE.get(description)
+        ?? PLANZER_TRANSLATED_EVENT_STAGE.get(description.toLowerCase().replace(/[.!]$/, ''));
+}
+/** The five steps the shared capability page draws, in the order it draws them. */
+export const PLANZER_ROUTE_STAGES = [
+    'registered',
+    'accepted',
+    'in_transit',
+    'out_for_delivery',
+    'delivered',
+];
+// The shared page labels its route steps in the recipient's language and
+// renders no code, so each stage is recognized by the substrings the German,
+// English, French and Italian labels have in common.
+const ROUTE_LABEL_RULES = [
+    ['delivered', ['ausgeliefert', 'delivered', 'livré', 'livrée', 'consegnat']],
+    ['out_for_delivery', ['in auslieferung', 'out for delivery', 'en livraison', 'in consegna']],
+    ['in_transit', ['umschlaglager', 'transfer depot', 'transshipment', 'plateforme', 'trasbordo']],
+    ['accepted', ['abholung', 'collection', 'collecte', 'ritiro']],
+    ['registered', ['erfasst', 'recorded', 'enregistr', 'registrat']],
+];
+/** The route stage a shared-page step label names, or null when it names none. */
+export function planzerRouteStage(label) {
+    const value = label.toLocaleLowerCase();
+    return ROUTE_LABEL_RULES.find(([, needles]) => needles.some((needle) => value.includes(needle)))?.[0] ?? null;
+}
+/** The shipment status a reached route stage implies. */
+export const PLANZER_ROUTE_STATUS = {
+    registered: 'pending',
+    accepted: 'in_transit',
+    in_transit: 'in_transit',
+    out_for_delivery: 'out_for_delivery',
+    delivered: 'delivered',
+};