universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/gofo/carrier.json

@@ -0,0 +1,80 @@
+{
+  "id": "gofo",
+  "displayName": "GOFO Express",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#fc4c02"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "gofo",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.gofo.com/us/track?searchID={trackingNumber}",
+    "canaryUrl": "https://www.gofo.com/us/track",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "delivered_at",
+      "eta"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "delivered_at"
+    ],
+    "discarded": [
+      "delivery_detail",
+      "proof_images",
+      "coordinates",
+      "departments",
+      "unlabelled_weight",
+      "eta"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "gofoexpress.com"
+      ],
+      "params": [
+        "searchID"
+      ]
+    },
+    {
+      "domains": [
+        "gofo.com"
+      ],
+      "path": "^/us/track/?$",
+      "params": [
+        "searchID"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "gofo-1",
+      "pattern": "^GFUS\\d{14}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/gofo/numbers.json

@@ -0,0 +1,59 @@
+{
+  "carrier": "gofo",
+  "records": [
+    {
+      "number": "GFUS01011884214272",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/gofo.json"
+      },
+      "expect": {
+        "carrier": "gofo",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "GFUS01011884214464",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/gofo.json"
+      },
+      "expect": {
+        "carrier": "gofo",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "GFUS01066030373313",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a9585f1402196fa26d71560",
+        "date": "2026-08-31"
+      },
+      "expect": {
+        "carrier": "gofo",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "GFUS01068091652674",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.courtlistener.com/docket/74763247/1/tikbooks-inc-v-chriss-sports-llc/",
+        "date": "2026-09-09"
+      },
+      "expect": {
+        "carrier": "gofo",
+        "confidence": "high"
+      },
+      "note": "Tracking number in a public court complaint that does not name the carrier; the GFUS prefix is GOFO's."
+    }
+  ]
+}

package/dist/carriers/gofo/parser.d.ts

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+/** The clock the adapter requests: GOFO prints Pacific clocks with their real offset. */
+export declare const GOFO_CLOCK_ZONE = "America/Los_Angeles";
+export declare function normalizeGofoNumber(raw: string): string;
+export declare function parseGofo(payload: unknown, rawNumber: string): CarrierResult;

package/dist/carriers/gofo/parser.js

@@ -0,0 +1,131 @@
+import { DateTime, IANAZone } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+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 { gofoStatus } from './status.js';
+const LABEL_CREATED = '100';
+/** The clock the adapter requests: GOFO prints Pacific clocks with their real offset. */
+export const GOFO_CLOCK_ZONE = 'America/Los_Angeles';
+// GOFO appends its support phone and email to some scans, in English or
+// Spanish; the public page removes that line before display.
+const CONTACT = String.raw `(?:\+?\(?\d[\d ().-]*\d|[\w.+-]+@[\w-]+(?:\.[\w-]+)+)`;
+const SUPPORT_LINE = new RegExp(String.raw `\s*(?:For delivery issues (?:&|and) tracking support, contact GOFO at|Para problemas de entrega y soporte de seguimiento, comun[ií]quese con GOFO al) ${CONTACT}(?:,? (?:or|and|o|y) ${CONTACT})*\.?$`, 'iu');
+export function normalizeGofoNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^GFUS\d{14}$/.test(number))
+        throw new TypeError('GOFO US requires a GFUS parcel reference');
+    return number;
+}
+function scanClock(value, scanZone) {
+    const raw = clean(value, 64);
+    const match = /^(\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?)(Z|[+-](?:0\d|1[0-4]):?[0-5]\d)?$/.exec(raw);
+    if (!match) {
+        // Offset-looking values must not exploit a permissive ISO parser.
+        if (raw.includes('T') && /(?:Z|[+-][\d:]+)$/i.test(raw))
+            throw new SchemaError('GOFO', 'GOFO returned an invalid scan timestamp');
+        return raw ? { provider_time_text: raw } : {};
+    }
+    const local = DateTime.fromISO(match[1], { zone: 'UTC' });
+    if (!local.isValid)
+        throw new SchemaError('GOFO', 'GOFO returned an invalid scan date');
+    if (!match[2])
+        return { local_time: local.toISO({ includeOffset: false, suppressMilliseconds: true }) };
+    const offset = match[2].replace(':', '');
+    if (offset !== 'Z' && Number(offset.slice(1, 3)) * 60 + Number(offset.slice(3)) > 840)
+        throw new SchemaError('GOFO', 'GOFO returned an invalid scan offset');
+    const time = explicitOffsetTime(raw);
+    if (!time)
+        throw new SchemaError('GOFO', 'GOFO returned an invalid scan timestamp');
+    // GOFO's "Local Time" setting pairs each scan's local clock with Pacific's
+    // offset. A requested Pacific clock must carry Pacific's offset at that time;
+    // the instant is then expressed in the scan's own zone when it has a valid one.
+    const instant = DateTime.fromMillis(time.timestamp, { zone: GOFO_CLOCK_ZONE });
+    if (instant.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== match[1].slice(0, 19))
+        throw new SchemaError('GOFO', 'GOFO returned a clock outside Pacific time');
+    const zone = clean(scanZone, 64);
+    return { time: (IANAZone.isValidZone(zone) ? instant.setZone(zone) : instant).toISO({ suppressMilliseconds: true }) };
+}
+/** Scan wording without a trailing support line; a scan worded only by that line keeps it. */
+function scanText(value) {
+    const text = clean(value, 1_000);
+    return (text.replace(SUPPORT_LINE, '') || text).slice(0, 500);
+}
+export function parseGofo(payload, rawNumber) {
+    const number = normalizeGofoNumber(rawNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('GOFO');
+    if (payload.code !== 200 || payload.success !== 1)
+        throw new IndeterminateError('GOFO', 'GOFO returned an inconclusive lookup');
+    if (!isRecord(payload.data) || !Array.isArray(payload.data.success) || payload.data.success.length > 25
+        || !payload.data.success.every(isRecord) || !isRecord(payload.data.error))
+        throw new SchemaError('GOFO');
+    const entries = payload.data.success;
+    const error = payload.data.error;
+    if (!entries.length && error.errorCount === 1 && Array.isArray(error.us) && error.us.length === 1 && error.us[0] === number
+        && Object.keys(error).every(key => ['errorCount', 'us'].includes(key)))
+        throw new NotFoundError('GOFO');
+    if (!entries.length)
+        throw new IndeterminateError('GOFO', 'GOFO returned no matching history');
+    // The GFUS number is the waybill. The tracking number repeats it or is the
+    // shipper's own reference, which must not name another GOFO parcel.
+    const reference = entries[0].trackingNumber;
+    const ownReference = reference === number || (typeof reference === 'string' && clean(reference, 100) !== ''
+        && !/^GFUS\d{14}$/.test(normalizeTrackingNumber(reference)));
+    if (entries.length !== 1 || entries[0].waybillNo !== number || !ownReference || error.errorCount !== 0) {
+        throw new SchemaError('GOFO', 'GOFO returned a different or ambiguous parcel');
+    }
+    const item = entries[0];
+    if (!Array.isArray(item.trackEventList) || item.trackEventList.length > 500 || !item.trackEventList.every(isRecord))
+        throw new SchemaError('GOFO');
+    if (!item.trackEventList.length)
+        throw new IndeterminateError('GOFO', 'GOFO returned no parcel scans');
+    // The public client renders this entire list without paging and ignores the
+    // counter, which can also count scans the list omits. A larger counter is
+    // accepted only while the list still reaches label creation; the summary
+    // check below binds its newest end.
+    if (!Number.isInteger(item.trackEventCount) || Number(item.trackEventCount) < item.trackEventList.length
+        || Number(item.trackEventCount) > 500) {
+        throw new IndeterminateError('GOFO', 'GOFO returned an inconsistent parcel event count');
+    }
+    if (Number(item.trackEventCount) > item.trackEventList.length && clean(item.trackEventList.at(-1).processCode, 32) !== LABEL_CREATED) {
+        throw new IndeterminateError('GOFO', 'GOFO returned incomplete parcel history');
+    }
+    const first = item.trackEventList[0];
+    const summary = item.lastTrackEvent;
+    if (!isRecord(summary) || ['processDate', 'processCode', 'processContent', 'processCity', 'processProvince', 'processLocation', 'processDeptId', 'processSecondCode', 'processTimeZone', 'processTimeZoneMapping'].some(key => summary[key] !== first[key])) {
+        throw new IndeterminateError('GOFO', 'GOFO latest summary does not match its first scan');
+    }
+    const events = [];
+    const seen = new Set();
+    for (const row of item.trackEventList) {
+        const code = clean(row.processCode, 32);
+        const rawDescription = scanText(row.processContent);
+        if (!code || !rawDescription)
+            throw new SchemaError('GOFO', 'GOFO returned an incomplete scan');
+        const mapped = gofoStatus(code);
+        if (mapped?.stage === 'delivered' && !/^Delivered(?:,|$)/.test(rawDescription))
+            throw new IndeterminateError('GOFO', 'GOFO returned inconsistent delivery evidence');
+        if ((row.waybillNo != null && row.waybillNo !== number) || (row.trackingNumber != null && row.trackingNumber !== reference)) {
+            throw new SchemaError('GOFO', 'GOFO returned a scan for a different parcel');
+        }
+        const timestamp = scanClock(row.processDate, row.processTimeZone);
+        const location = [clean(row.processCity, 100), clean(row.processProvince, 20)].filter(Boolean).join(', ');
+        const description = mapped?.stage === 'delivered' ? 'Delivered' : rawDescription;
+        const event = { ...timestamp, description, provider_code: code,
+            ...(location ? { location } : {}), ...(mapped ? { stage: mapped.stage } : {}) };
+        const key = JSON.stringify(event);
+        if (!seen.has(key)) {
+            seen.add(key);
+            events.push(event);
+        }
+    }
+    const latest = events[0];
+    const current = gofoStatus(String(latest.provider_code));
+    return { status: current?.status ?? 'unknown', ...(current ? { current_stage: current.stage } : {}),
+        last_status_text: latest.description, last_update: latest.time ?? null, last_update_local: latest.local_time ?? null,
+        expected_delivery: null,
+        ...(current?.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        ...(item.toCountry === 'USA' ? { destination_country: 'US' } : {}), events: events.slice(0, 100) };
+}

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

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

package/dist/carriers/gofo/status.js

@@ -0,0 +1,7 @@
+const CODES = new Map([
+    ['100', { status: 'pending', stage: 'registered' }],
+    ...['200', '201', '202', '203'].map(code => [code, { status: 'in_transit', stage: 'in_transit' }]),
+    ['208', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['205', { status: 'delivered', stage: 'delivered' }],
+]);
+export function gofoStatus(code) { return CODES.get(code); }

package/dist/carriers/gofo/statuses.json

@@ -0,0 +1,54 @@
+{
+  "carrier": "gofo",
+  "entries": [
+    {
+      "code": "100",
+      "wording": "Shipping Label Created",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "202",
+      "wording": "Arrived at GOFO Regional Hub",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "200",
+      "wording": "Departed GOFO Regional Hub",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "201",
+      "wording": "Arrived at GOFO Delivery Station",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "203",
+      "wording": "Departed GOFO Delivery Station",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "208",
+      "wording": "Out for Delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "205",
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/heppner/adapter.d.ts

@@ -0,0 +1,27 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+interface HeppnerCredential {
+    trackingNumber: string;
+    postcode: string;
+    countryCode: 'CH' | 'FR';
+}
+export declare function normalizeHeppnerTrackingNumber(raw: string): string;
+export declare function normalizeHeppnerCredential(rawTrackingNumber: string, rawPostcode: string): HeppnerCredential;
+export declare function heppnerSearchUrl(rawTrackingNumber: string, rawPostcode: string): string;
+export declare function parseHeppnerCapability(rawCapability: string, rawTrackingNumber: string, rawPostcode: string): string;
+export declare function heppnerDetailUrl(capability: string): string;
+export declare function heppnerTrackingPageUrl(capability: string): string;
+export declare function parseHeppnerTrackingResponse(payload: unknown, rawTrackingNumber: string): CarrierResult;
+export interface HeppnerTrackerOptions {
+    timeoutMs?: number;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+}
+export declare class HeppnerTracker {
+    readonly timeoutMs: number;
+    readonly fetcher?: typeof fetch;
+    constructor(options?: HeppnerTrackerOptions);
+    fetch(rawTrackingNumber: string, rawPostcode: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;
+export {};

package/dist/carriers/heppner/adapter.js

@@ -0,0 +1,247 @@
+/**
+ * Heppner recipient tracking.
+ *
+ * The public recipient page asks for a shipment receipt number plus the
+ * delivery postcode, and the portal answers in two hops: a search call that
+ * returns a base64 capability binding both values, then a detail call that
+ * returns the shipment with its scan list. The capability is verified against
+ * the credential we sent before it is used, so a portal that answered for a
+ * different shipment cannot redirect the lookup.
+ *
+ * Privacy: the detail payload also carries shipment parties, references,
+ * merchandise descriptions, appointment tokens and depot addresses. `parse()`
+ * builds events from an explicit allowlist (time, our own description, stage,
+ * event code) and keeps no location at all, because the only location field
+ * the endpoint offers is the delivery address.
+ */
+import { Buffer } from 'node:buffer';
+import { DateTime } from 'luxon';
+import { InputRequiredError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyHeppnerEvent, heppnerCode } from './status.js';
+const SEARCH_ENDPOINT = 'https://myportal.heppner-group.com/api/recipient/search/expedition';
+const DETAIL_ENDPOINT = 'https://myportal.heppner-group.com/api/recipient/search/detailexpedition';
+const TRACKING_PAGE = 'https://myportal.heppner-group.com/tracking';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+/**
+ * Kept local rather than taken from core/time: the portal always stamps an
+ * offset, and this adapter normalizes every scan to UTC instead of preserving
+ * the source offset, which `explicitOffsetTime` does.
+ */
+function eventTime(value) {
+    const raw = cleanScalar(value, 64);
+    if (!raw)
+        return null;
+    const parsed = DateTime.fromISO(raw, { setZone: true });
+    const iso = parsed.toUTC().toISO({ suppressMilliseconds: true });
+    return parsed.isValid && iso ? { iso, timestamp: parsed.toMillis() } : null;
+}
+export function normalizeHeppnerTrackingNumber(raw) {
+    const trackingNumber = raw.replace(/\s/g, '');
+    if (!/^\d{8}$/.test(trackingNumber)) {
+        throw new TypeError('Heppner tracking numbers must contain exactly 8 digits');
+    }
+    return trackingNumber;
+}
+export function normalizeHeppnerCredential(rawTrackingNumber, rawPostcode) {
+    const trackingNumber = normalizeHeppnerTrackingNumber(rawTrackingNumber);
+    const postcode = rawPostcode.trim();
+    if (!/^\d{4,5}$/.test(postcode)) {
+        throw new TypeError('Heppner requires a four-digit Swiss or five-digit French delivery postcode');
+    }
+    return {
+        trackingNumber,
+        postcode,
+        countryCode: postcode.length === 4 ? 'CH' : 'FR',
+    };
+}
+export function heppnerSearchUrl(rawTrackingNumber, rawPostcode) {
+    const credential = normalizeHeppnerCredential(rawTrackingNumber, rawPostcode);
+    const url = new URL(SEARCH_ENDPOINT);
+    url.search = new URLSearchParams({
+        zipCode: credential.postcode,
+        receipt: credential.trackingNumber,
+        countryCode: credential.countryCode,
+    }).toString();
+    return url.toString();
+}
+function expectedCapabilityValue(credential) {
+    return `${credential.trackingNumber}&${credential.postcode}&${credential.countryCode}`;
+}
+export function parseHeppnerCapability(rawCapability, rawTrackingNumber, rawPostcode) {
+    const credential = normalizeHeppnerCredential(rawTrackingNumber, rawPostcode);
+    const capability = cleanScalar(rawCapability, 512);
+    if (!capability
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(capability)) {
+        throw new SchemaError('Heppner', 'Heppner returned an invalid tracking capability');
+    }
+    let decoded = '';
+    try {
+        decoded = Buffer.from(capability, 'base64').toString('utf8');
+    }
+    catch (error) {
+        throw new SchemaError('Heppner', 'Heppner returned an invalid tracking capability', { cause: error });
+    }
+    if (decoded !== expectedCapabilityValue(credential)) {
+        throw new SchemaError('Heppner', 'Heppner returned a capability for a different shipment');
+    }
+    return capability;
+}
+export function heppnerDetailUrl(capability) {
+    const normalized = cleanScalar(capability, 512);
+    if (!normalized || !/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) {
+        throw new SchemaError('Heppner', 'Heppner tracking capability is invalid');
+    }
+    const url = new URL(DETAIL_ENDPOINT);
+    url.searchParams.set('expedition', normalized);
+    return url.toString();
+}
+export function heppnerTrackingPageUrl(capability) {
+    const normalized = cleanScalar(capability, 512);
+    if (!normalized || !/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) {
+        throw new SchemaError('Heppner', 'Heppner tracking capability is invalid');
+    }
+    return `${TRACKING_PAGE}/${encodeURIComponent(normalized)}`;
+}
+function responseReceipt(value) {
+    const normalized = cleanScalar(value, 32);
+    return /^\d{8}$/.test(normalized) ? normalized : '';
+}
+function rawEvents(shipment) {
+    return Array.isArray(shipment.events) ? shipment.events.filter(isRecord) : [];
+}
+function parseEvents(shipment) {
+    const parsedEvents = [];
+    const seen = new Set();
+    rawEvents(shipment).slice(0, MAX_EVENTS_TO_INSPECT).forEach((rawEvent, index) => {
+        const providerCode = heppnerCode(rawEvent.code) || heppnerCode(rawEvent.event);
+        const time = eventTime(rawEvent.event_date) ?? eventTime(rawEvent.date);
+        if (!time)
+            return;
+        const classified = classifyHeppnerEvent(rawEvent.step, rawEvent.state, providerCode);
+        const identity = `${time.iso}\u0000${providerCode}\u0000${classified.stage}`;
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        parsedEvents.push({
+            event: {
+                time: time.iso,
+                location: '',
+                description: classified.description,
+                stage: classified.stage,
+                ...(providerCode ? { provider_code: providerCode } : {}),
+            },
+            status: classified.status,
+            timestamp: time.timestamp,
+            index,
+        });
+    });
+    parsedEvents.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    return parsedEvents.slice(0, MAX_EVENTS_TO_RETURN);
+}
+export function parseHeppnerTrackingResponse(payload, rawTrackingNumber) {
+    const trackingNumber = normalizeHeppnerTrackingNumber(rawTrackingNumber);
+    if (!Array.isArray(payload)) {
+        throw new SchemaError('Heppner', 'Heppner returned an invalid tracking response');
+    }
+    if (payload.length === 0)
+        throw new NotFoundError('Heppner');
+    const shipments = payload.filter(isRecord);
+    if (shipments.length !== payload.length) {
+        throw new SchemaError('Heppner', 'Heppner returned an invalid shipment entry');
+    }
+    const matching = shipments.find((shipment) => responseReceipt(shipment.receipt) === trackingNumber);
+    if (!matching) {
+        const hasIdentifier = shipments.some((shipment) => responseReceipt(shipment.receipt));
+        if (hasIdentifier)
+            throw new SchemaError('Heppner', 'Heppner returned a different shipment');
+        throw new SchemaError('Heppner', 'Heppner did not return a shipment identifier');
+    }
+    const parsed = parseEvents(matching);
+    if (parsed.length === 0)
+        throw new SchemaError('Heppner', 'Heppner did not return tracking history');
+    const latest = parsed[0];
+    const latestKnown = parsed.find((item) => item.status !== 'unknown');
+    return {
+        status: latest.status !== 'unknown' ? latest.status : latestKnown?.status ?? 'unknown',
+        current_stage: latest.status !== 'unknown'
+            ? latest.event.stage ?? 'in_transit'
+            : latestKnown?.event.stage ?? 'in_transit',
+        last_status_text: latest.event.description ?? 'Tracking information received',
+        last_update: latest.event.time ?? null,
+        expected_delivery: null,
+        timezone: 'Europe/Paris',
+        events: parsed.map(({ event }) => event),
+    };
+}
+function requestHeaders(accept, origin = 'https://www.heppner-group.com') {
+    return {
+        Accept: accept,
+        'Accept-Language': 'fr-FR,fr;q=0.9',
+        Origin: origin,
+        Referer: 'https://www.heppner-group.com/destinataire-suivez-votre-marchandise/',
+        'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+    };
+}
+export class HeppnerTracker {
+    timeoutMs;
+    fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Heppner timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber, rawPostcode) {
+        const credential = normalizeHeppnerCredential(rawTrackingNumber, rawPostcode);
+        const search = await fetchBounded(heppnerSearchUrl(credential.trackingNumber, credential.postcode), { headers: requestHeaders('text/plain,*/*;q=0.8') }, {
+            provider: 'Heppner shipment search',
+            timeoutMs: this.timeoutMs,
+            maxBytes: 2_048,
+            fetcher: this.fetcher,
+            allowHttpError: true,
+        });
+        if (search.response.status === 404)
+            throw new NotFoundError('Heppner');
+        if (!search.response.ok) {
+            throw new UpstreamHttpError('Heppner shipment search', search.response.status);
+        }
+        const capability = parseHeppnerCapability(decodeText(search.bytes), credential.trackingNumber, credential.postcode);
+        const detail = await fetchBounded(heppnerDetailUrl(capability), {
+            headers: {
+                ...requestHeaders('application/json', 'https://myportal.heppner-group.com'),
+                Referer: heppnerTrackingPageUrl(capability),
+            },
+        }, {
+            provider: 'Heppner tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            fetcher: this.fetcher,
+            allowHttpError: true,
+        });
+        if (detail.response.status === 404)
+            throw new NotFoundError('Heppner');
+        if (!detail.response.ok) {
+            throw new UpstreamHttpError('Heppner tracking', detail.response.status);
+        }
+        return parseHeppnerTrackingResponse(parseJsonBytes(detail.bytes, 'Heppner'), credential.trackingNumber);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new HeppnerTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'heppner',
+        steps: ['direct'],
+        track: async (input) => {
+            const postcode = input.postcode?.trim() ?? '';
+            if (!postcode)
+                throw new InputRequiredError('Heppner', 'the delivery postcode');
+            return tracker.fetch(input.number, postcode);
+        },
+    };
+};