universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,84 @@
+{
+  "id": "swiss-post",
+  "displayName": "Swiss Post",
+  "aliases": [
+    "Die Post",
+    "La Poste Suisse",
+    "La Posta Svizzera",
+    "Swiss Post Ltd"
+  ],
+  "region": {
+    "countries": [
+      "CH",
+      "LI"
+    ]
+  },
+  "brand": {
+    "color": "#ffcc00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "swiss-post",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://service.post.ch/ekp-web/ui/entry/search/{trackingNumber}",
+    "canaryUrl": "https://service.post.ch/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "eta_window",
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "delivery_instructions"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "delivery_instructions"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "service.post.ch"
+      ],
+      "path": "/entry/search/([^/?#]+)"
+    }
+  ],
+  "detection": [
+    {
+      "id": "swiss-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}CH$",
+      "confidence": "high",
+      "checksum": "s10"
+    },
+    {
+      "id": "swiss-post-2",
+      "pattern": "^9[89]\\d{16}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/swiss-post/numbers.json

@@ -0,0 +1,55 @@
+{
+  "carrier": "swiss-post",
+  "records": [
+    {
+      "number": "98.11.223344.55667788",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "99.34.123456.12345678",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "RA123456785CH",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "RS908247336CH",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    }
+  ]
+}

package/dist/carriers/swiss-post/status.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Swiss Post status classification.
+ *
+ * Two independent vocabularies meet here. `globalStatus` is the shipment-level
+ * summary the portal shows at the top of the page. Event codes are the last
+ * segment of a dotted `eventCode` such as `PARCEL.*.1.1003`, and they are the
+ * authority for the current stage: the summary lags behind (a MyPost24 deposit
+ * reads `DELIVERED` while the parcel is still waiting in the locker).
+ *
+ * Only codes with a confirmed meaning are mapped. Anything else is left without
+ * a stage so the sync can classify the wording and record the code for review.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+/** Shipment-level `globalStatus` → status. The event codes below refine it. */
+export declare const STATUS_MAP: Map<string, CarrierStatus>;
+/** Wording for codes the translation service does not resolve. */
+export declare const FALLBACK_EVENT_LABELS: Record<string, string>;
+/** Parcel event codes (the last dotted segment) with a confirmed stage. */
+export declare const EVENT_STAGE_BY_CODE: Record<string, Stage>;
+export declare const LETTER_IMPORT_STAGE_BY_CODE: Record<string, Stage>;
+/** The shipment status implied by the newest event's stage. */
+export declare const STAGE_STATUS: Record<string, CarrierStatus>;
+/** Only `LETTER.*.90.*` scans use the import table; everything else uses the parcel table. */
+export declare const LETTER_IMPORT_EVENT: RegExp;
+/** The stage for a full dotted event code, or undefined when the code is not mapped. */
+export declare function swissPostEventStage(eventCode: string): Stage | undefined;

package/dist/carriers/swiss-post/status.js

@@ -0,0 +1,64 @@
+/** Shipment-level `globalStatus` → status. The event codes below refine it. */
+export const STATUS_MAP = new Map([
+    ['REPORTED', 'pending'],
+    ['REGISTERED', 'pending'],
+    ['TO_BE_DELIVERED', 'in_transit'],
+    ['IN_DELIVERY', 'out_for_delivery'],
+    ['DELIVERED', 'delivered'],
+    ['MISSED_DELIVERY', 'exception'],
+    ['NOT_DELIVERED', 'exception'],
+    ['RETURNED', 'exception'],
+    ['CUSTOMS', 'in_transit'],
+]);
+/** Wording for codes the translation service does not resolve. */
+export const FALLBACK_EVENT_LABELS = {
+    '600': 'Your shipment will shortly be handed over to Swiss Post',
+    '1003': 'Loading into delivery vehicle',
+    '1201': 'Sorted for delivery',
+    '1202': 'Shipment was sorted',
+};
+/** Parcel event codes (the last dotted segment) with a confirmed stage. */
+export const EVENT_STAGE_BY_CODE = {
+    '600': 'registered',
+    '820': 'in_transit',
+    '1003': 'out_for_delivery',
+    '1201': 'in_transit',
+    '1202': 'in_transit',
+    '2102': 'ready_for_pickup',
+    '3600': 'returned',
+    '4600': 'delivered',
+};
+// International letter/packet scans used for postal handoffs (including DHL
+// Kleinpaket). Their wording can otherwise imply delivery or active customs.
+export const LETTER_IMPORT_STAGE_BY_CODE = {
+    '620': 'registered',
+    '803': 'customs',
+    '804': 'in_transit',
+    '805': 'in_transit',
+    '818': 'in_transit',
+    '912': 'accepted',
+    '915': 'in_transit',
+    '1001': 'in_transit',
+    '1213': 'in_transit',
+    '1218': 'in_transit',
+};
+/** The shipment status implied by the newest event's stage. */
+export const STAGE_STATUS = {
+    registered: 'pending',
+    accepted: 'in_transit',
+    in_transit: 'in_transit',
+    out_for_delivery: 'out_for_delivery',
+    delivered: 'delivered',
+    customs: 'in_transit',
+    failed_attempt: 'exception',
+    ready_for_pickup: 'in_transit',
+    returned: 'exception',
+};
+/** Only `LETTER.*.90.*` scans use the import table; everything else uses the parcel table. */
+export const LETTER_IMPORT_EVENT = /^LETTER\.[^.]+\.90\./;
+/** The stage for a full dotted event code, or undefined when the code is not mapped. */
+export function swissPostEventStage(eventCode) {
+    const code = eventCode.split('.').at(-1) ?? '';
+    return (LETTER_IMPORT_EVENT.test(eventCode) ? LETTER_IMPORT_STAGE_BY_CODE[code] : undefined)
+        ?? EVENT_STAGE_BY_CODE[code];
+}

package/dist/carriers/swiss-post/statuses.json

@@ -0,0 +1,33 @@
+{
+  "carrier": "swiss-post",
+  "entries": [
+    { "code": "REPORTED", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'pending'." },
+    { "code": "REGISTERED", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'pending'." },
+    { "code": "TO_BE_DELIVERED", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus." },
+    { "code": "IN_DELIVERY", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus." },
+    { "code": "DELIVERED", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; overridden by the newest event code, so a MyPost24 deposit stays ready_for_pickup." },
+    { "code": "MISSED_DELIVERY", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'exception'." },
+    { "code": "NOT_DELIVERED", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'exception'." },
+    { "code": "RETURNED", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'exception'." },
+    { "code": "CUSTOMS", "stage": "customs", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Shipment-level globalStatus; reported as status 'in_transit'." },
+    { "code": "600", "wording": "Your shipment will shortly be handed over to Swiss Post", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Parcel event code; also carries a hard-coded fallback wording." },
+    { "code": "820", "wording": "Shipment is being forwarded", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Parcel event code." },
+    { "code": "1003", "wording": "Loading into delivery vehicle", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Parcel event code; also carries a hard-coded fallback wording." },
+    { "code": "1201", "wording": "Sorted for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Parcel event code; also carries a hard-coded fallback wording." },
+    { "code": "1202", "wording": "Shipment was sorted", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Parcel event code; also carries a hard-coded fallback wording." },
+    { "code": "2102", "wording": "Deposited in the MyPost24 machine", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Parcel event code. Arrival in a locker, not a delivery, even when the shipment summary says DELIVERED." },
+    { "code": "3600", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Parcel event code." },
+    { "code": "4600", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Parcel event code." },
+    { "code": "LETTER.*.90.620", "wording": "Consignment recorded by the foreign sender (data delivered)", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan; the wording would otherwise read as a delivery." },
+    { "code": "LETTER.*.90.803", "wording": "Customs clearance process underway", "language": "en", "stage": "customs", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "LETTER.*.90.804", "wording": "Completion of customs clearance process", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Completion, not active clearance." },
+    { "code": "LETTER.*.90.805", "wording": "Completion of customs clearance process", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Completion, not active clearance." },
+    { "code": "LETTER.*.90.818", "wording": "Arrival in destination country", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "LETTER.*.90.912", "wording": "Time at which your consignment was mailed", "language": "en", "stage": "accepted", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "LETTER.*.90.915", "wording": "The consignment has left the border point", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "LETTER.*.90.1001", "wording": "Arrival at the collection/delivery point", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Arrival at the office, not a handover to the recipient." },
+    { "code": "LETTER.*.90.1213", "wording": "Sorted for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "LETTER.*.90.1218", "wording": "Sorted for delivery", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "International letter/packet import scan." },
+    { "code": "any other event code", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Left without a stage: the event keeps its translated wording and its raw code, and the sync classifies and records it for review." }
+  ]
+}

package/dist/carriers/swiss-post-cargo/adapter.d.ts

@@ -0,0 +1,19 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export interface SwissPostCargoOptions {
+    timeoutMs?: number;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+    /** Test seam for the clock that decides which reference shipments are current. */
+    now?: () => number;
+}
+export declare function normalizeSwissPostCargoTrackingNumber(raw: string): string;
+export declare function swissPostCargoTrackingUrl(raw: string): string;
+export declare function parseSwissPostCargoResponse(payload: unknown, rawTrackingNumber: string, now?: number): CarrierResult;
+export declare class SwissPostCargoTracker {
+    #private;
+    readonly timeoutMs: number;
+    constructor(options?: number | SwissPostCargoOptions);
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/swiss-post-cargo/adapter.js

@@ -0,0 +1,173 @@
+import { InputRequiredError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { isoTime, zonedTime } from '../../core/time/index.js';
+import { cleanScalar, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { referenceConsignment } from './reference.js';
+import { statusFor } from './status.js';
+// Protocol provenance (inspected 2026-08-30): the source map published by the
+// official public tracker posts { Identifier } to this anonymous endpoint and
+// treats a null Data property as a clean not-found result.
+// https://apv.swisspost-cargo.com/static/js/907.9a0b939a.chunk.js.map
+const TRACKING_API = 'https://eosapi.swisspost-cargo.com/api/trackandtrace/public';
+const TRACKING_PAGE = 'https://apv.swisspost-cargo.com/public/trackandtrace';
+const PROVIDER = 'Swiss Post Cargo';
+const ZONE = 'Europe/Zurich';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+/**
+ * The endpoint sends Swiss wall-clock ISO-8601 without an offset
+ * (`2026-08-30T12:30:00.777`). It is read in Europe/Zurich, never in the
+ * server's zone, and so are the dotted and slashed fallbacks. An explicit
+ * offset or `Z` is kept as sent.
+ */
+function eventTimestamp(value) {
+    return isoTime(value, ZONE)
+        ?? zonedTime(value, 'dd.MM.yyyy HH:mm:ss', ZONE)
+        ?? zonedTime(value, 'dd.MM.yyyy HH:mm', ZONE)
+        ?? zonedTime(value, 'dd/MM/yyyy HH:mm:ss', ZONE);
+}
+export function normalizeSwissPostCargoTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^(?=.*\d)[A-Z0-9]{6,40}$/.test(value)) {
+        throw new InputRequiredError(PROVIDER, 'a 6- to 40-character barcode or reference');
+    }
+    return value;
+}
+export function swissPostCargoTrackingUrl(raw) {
+    return `${TRACKING_PAGE}/${encodeURIComponent(normalizeSwissPostCargoTrackingNumber(raw))}`;
+}
+export function parseSwissPostCargoResponse(payload, rawTrackingNumber, now = Date.now()) {
+    const trackingNumber = normalizeSwissPostCargoTrackingNumber(rawTrackingNumber);
+    if (!isRecord(payload) || !Object.hasOwn(payload, 'Data')) {
+        throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned an invalid tracking response');
+    }
+    if (payload.Data === null)
+        throw new NotFoundError(PROVIDER);
+    if (!Array.isArray(payload.Data) || payload.Data.length === 0) {
+        throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned an invalid tracking response');
+    }
+    let shipments = payload.Data.filter(isRecord);
+    if (shipments.length === 0) {
+        throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned an invalid tracking response');
+    }
+    const responseType = Number(payload.Type);
+    if (responseType !== 1 && responseType !== 2 && responseType !== 3) {
+        throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned an invalid tracking response type');
+    }
+    if (responseType !== 2) {
+        const identifiers = shipments
+            .map((shipment) => cleanScalar(shipment.Identifier, 64).toLocaleUpperCase('en-US'))
+            .filter(Boolean);
+        if (identifiers.length === 0) {
+            throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned no shipment identifier');
+        }
+        if (!identifiers.includes(trackingNumber)) {
+            throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned a different shipment');
+        }
+        shipments = shipments.filter((shipment) => (cleanScalar(shipment.Identifier, 64).toLocaleUpperCase('en-US') === trackingNumber));
+    }
+    // Type 3, which the tracker's source map does not name, relays Swiss Post's
+    // own scans (placeholder `PST` codes, no place) for a parcel barcode the eos
+    // system does not hold. The parcel is Swiss Post's, so this is a not-found
+    // here and routing asks the Swiss Post adapter instead.
+    if (responseType === 3) {
+        throw new NotFoundError(PROVIDER, 'Swiss Post Cargo only relays Swiss Post tracking for this barcode');
+    }
+    if (responseType === 2) {
+        shipments = referenceConsignment(shipments, (shipment) => (Array.isArray(shipment.History) ? shipment.History.filter(isRecord) : []).map((row) => eventTimestamp(row.TimeStamp)?.timestamp ?? Number.NaN), PROVIDER, now);
+    }
+    const parsedEvents = [];
+    const seen = new Set();
+    let index = 0;
+    for (const shipment of shipments.slice(0, 100)) {
+        if (!Array.isArray(shipment.History))
+            continue;
+        for (const candidate of shipment.History.slice(0, 500)) {
+            if (!isRecord(candidate))
+                continue;
+            const time = eventTimestamp(candidate.TimeStamp);
+            const description = cleanScalar(candidate.Description);
+            if (!time || !description)
+                continue;
+            const location = cleanScalar(candidate.City, 120);
+            const code = cleanScalar(candidate.Status, 32).toLocaleUpperCase('en-US');
+            const identity = JSON.stringify([time.iso, location, description, code]);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            const classified = statusFor(code, description);
+            parsedEvents.push({
+                event: {
+                    time: time.iso,
+                    location,
+                    description,
+                    stage: classified.stage,
+                    ...(code ? { provider_code: code } : {}),
+                },
+                status: classified.status,
+                timestamp: time.timestamp,
+                index,
+            });
+            index += 1;
+        }
+    }
+    parsedEvents.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    const events = parsedEvents.slice(0, 100);
+    if (events.length === 0) {
+        throw new SchemaError(PROVIDER, 'Swiss Post Cargo returned no usable tracking events');
+    }
+    const latest = events[0];
+    return {
+        status: latest.status,
+        current_stage: latest.event.stage,
+        last_status_text: latest.event.description,
+        last_update: latest.event.time,
+        expected_delivery: null,
+        timezone: ZONE,
+        events: events.map(({ event }) => event),
+        tracking_url: swissPostCargoTrackingUrl(trackingNumber),
+    };
+}
+export class SwissPostCargoTracker {
+    timeoutMs;
+    #fetcher;
+    #now;
+    constructor(options = {}) {
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, fetcher, now = Date.now } = typeof options === 'number' ? { timeoutMs: options } : options;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new TypeError('Swiss Post Cargo timeout must be positive');
+        }
+        this.timeoutMs = timeoutMs;
+        this.#fetcher = fetcher;
+        this.#now = now;
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizeSwissPostCargoTrackingNumber(rawTrackingNumber);
+        const { bytes } = await fetchBounded(TRACKING_API, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Accept-Language': 'en-CH,en;q=0.9',
+                'Content-Type': 'application/json',
+                Origin: 'https://apv.swisspost-cargo.com',
+                Referer: `${TRACKING_PAGE}/`,
+                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+            },
+            body: JSON.stringify({ Identifier: trackingNumber }),
+        }, {
+            provider: 'Swiss Post Cargo tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
+        });
+        return parseSwissPostCargoResponse(parseJsonBytes(bytes, PROVIDER), trackingNumber, this.#now());
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new SwissPostCargoTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'swiss-post-cargo',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/swiss-post-cargo/carrier.json

@@ -0,0 +1,60 @@
+{
+  "id": "swiss-post-cargo",
+  "displayName": "Swiss Post Cargo",
+  "aliases": [
+    "Hugger"
+  ],
+  "region": {
+    "countries": [
+      "CH"
+    ]
+  },
+  "brand": {
+    "color": "#ffcc00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "swiss-post-cargo",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://apv.swisspost-cargo.com/public/trackandtrace/{trackingNumber}",
+    "canaryUrl": "https://apv.swisspost-cargo.com/public/trackandtrace",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "recipient_name",
+      "recipient_address"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "apv.swisspost-cargo.com"
+      ],
+      "path": "^/public/trackandtrace/([^/?#]+)/?$"
+    }
+  ],
+  "detection": []
+}

package/dist/carriers/swiss-post-cargo/numbers.json

@@ -0,0 +1,23 @@
+{
+  "carrier": "swiss-post-cargo",
+  "records": [
+    {
+      "number": "12345678",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://portal-de1.swisspost-cargo.com/Track",
+        "date": "2026-09-30"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "mondial-relay",
+          "heppner"
+        ]
+      },
+      "note": "Example Sendungsnummer from the carrier's tracking form, where it goes with a Betriebsnummer; on its own eos matches it to unrelated shipments. The source attributes it to Swiss Post Cargo, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/swiss-post-cargo/reference.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The barcodes an eos customer reference (`Type: 2`) stands for in a parcel.
+ *
+ * Shippers reuse references, so an answer can list unrelated shipments years
+ * apart; the official tracker shows each barcode on its own behind a filter. A
+ * parcel needs one consignment: the barcodes first scanned within a day of the
+ * newest one, read only when they have a scan from the last 60 days and no
+ * other barcode does. Any other answer names no single current shipment and is
+ * a not-found. `scanTimes` gives one instant per history row, NaN when the row's
+ * time cannot be read; barcodes without a dated scan cannot be placed and are
+ * dropped.
+ */
+export declare function referenceConsignment<T>(shipments: readonly T[], scanTimes: (shipment: T) => number[], provider: string, now: number): T[];

package/dist/carriers/swiss-post-cargo/reference.js

@@ -0,0 +1,48 @@
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+const DAY_MS = 24 * 3_600_000;
+/** The pieces of one consignment are announced and picked up together. */
+const CONSIGNMENT_SPREAD_MS = DAY_MS;
+/** Carrier recognition's window: a shipment quiet this long is an older one reusing the reference. */
+const CURRENT_MS = 60 * DAY_MS;
+/**
+ * The barcodes an eos customer reference (`Type: 2`) stands for in a parcel.
+ *
+ * Shippers reuse references, so an answer can list unrelated shipments years
+ * apart; the official tracker shows each barcode on its own behind a filter. A
+ * parcel needs one consignment: the barcodes first scanned within a day of the
+ * newest one, read only when they have a scan from the last 60 days and no
+ * other barcode does. Any other answer names no single current shipment and is
+ * a not-found. `scanTimes` gives one instant per history row, NaN when the row's
+ * time cannot be read; barcodes without a dated scan cannot be placed and are
+ * dropped.
+ */
+export function referenceConsignment(shipments, scanTimes, provider, now) {
+    const scanned = shipments.map((shipment) => ({ shipment, times: scanTimes(shipment) }));
+    const timelines = scanned.flatMap(({ shipment, times }) => {
+        const dated = times.filter(Number.isFinite);
+        if (dated.length === 0)
+            return [];
+        return [{
+                shipment,
+                first: dated.reduce((earliest, time) => Math.min(earliest, time)),
+                last: dated.reduce((latest, time) => Math.max(latest, time)),
+            }];
+    });
+    if (timelines.length === 0) {
+        if (scanned.some(({ times }) => times.length > 0)) {
+            throw new SchemaError(provider, `${provider} returned reference scans without a readable time`);
+        }
+        throw new NotFoundError(provider, `${provider} has no scans for this reference yet`);
+    }
+    const newest = timelines.reduce((latest, timeline) => Math.max(latest, timeline.first), Number.NEGATIVE_INFINITY);
+    const joins = (timeline) => newest - timeline.first <= CONSIGNMENT_SPREAD_MS;
+    const current = (timeline) => now - timeline.last < CURRENT_MS;
+    const consignment = timelines.filter(joins);
+    if (!consignment.some(current)) {
+        throw new NotFoundError(provider, `${provider} only has older shipments for this reference`);
+    }
+    if (timelines.some((timeline) => !joins(timeline) && current(timeline))) {
+        throw new NotFoundError(provider, `${provider} has several shipments for this reference`);
+    }
+    return consignment.map((timeline) => timeline.shipment);
+}

package/dist/carriers/swiss-post-cargo/status.d.ts

@@ -0,0 +1,13 @@
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+/** Lower-cased, accent-free wording, for language-independent matching. */
+export declare function comparable(value: unknown): string;
+/**
+ * Confirmed codes (observed on the public tracker, 2026-08-30): DLV/POD/P40/
+ * IMG/SIG accompany a delivery, SCA a delivery-round scan, NTF an
+ * announcement, RFS an acceptance. Everything else stays in transit.
+ */
+export declare function statusFor(code: string, description: string): {
+    status: CarrierStatus;
+    stage: Stage;
+};