@shopickup/adapters-foxpost 0.0.1

package/dist/mappers/index.js

@@ -0,0 +1,270 @@
+/**
+ * Mappers for Foxpost adapter
+ * Converts between canonical Shopickup types and Foxpost API types
+ */
+import { mapFoxpostStatusCode } from './trackStatus.js';
+const FOXPOST_SIZES = ["xs", "s", "m", "l", "xl"];
+/**
+ * Map canonical Address (from Parcel.sender or Parcel.recipient) to Foxpost address format
+ */
+export function mapAddressToFoxpost(addr) {
+    return {
+        name: addr.name.substring(0, 150), // Foxpost max length
+        phone: addr.phone || "",
+        email: addr.email || "",
+        city: addr.city?.substring(0, 25),
+        zip: addr.postalCode,
+        address: addr.street?.substring(0, 150),
+        country: addr.country || "HU", // Default to Hungary
+    };
+}
+/**
+ * Determine parcel size based on dimensions or weight
+ * Foxpost sizes: xs, s, m, l, xl
+ */
+export function determineFoxpostSize(parcel) {
+    // If no dimensions, default to 's' (small)
+    if (!parcel.package.dimensionsCm) {
+        return "s";
+    }
+    const { length, width, height } = parcel.package.dimensionsCm;
+    const volume = length * width * height;
+    // Very rough heuristic based on volume
+    let candidate = "xs";
+    if (volume < 5000) {
+        candidate = "xs";
+    }
+    else if (volume < 15000) {
+        candidate = "s";
+    }
+    else if (volume < 50000) {
+        candidate = "m";
+    }
+    else if (volume < 100000) {
+        candidate = "l";
+    }
+    else {
+        candidate = "xl";
+    }
+    return candidate;
+}
+/**
+ * Map canonical Parcel to Foxpost CreateParcelRequest (strongly-typed)
+ * Returns typed FoxCreateParcelRequestItem with lenient validation support
+ *
+ * Handles both HOME delivery (full address) and PICKUP_POINT delivery (APM/locker)
+ */
+export function mapParcelToFoxpostRequest(parcel, options = {}) {
+    const delivery = parcel.recipient.delivery;
+    const isHomeDelivery = delivery.method === 'HOME';
+    const recipientAddr = isHomeDelivery
+        ? delivery.address
+        : undefined;
+    const recipient = {
+        name: parcel.recipient.contact.name.substring(0, 150),
+        phone: parcel.recipient.contact.phone || "",
+        email: parcel.recipient.contact.email || "",
+        city: recipientAddr?.city?.substring(0, 25),
+        zip: recipientAddr?.postalCode,
+        address: recipientAddr?.street?.substring(0, 150),
+        country: recipientAddr?.country || "HU",
+    };
+    // COD amount from parcel if present, default to 0
+    const codAmount = parcel.cod?.amount.amount ?? 0;
+    const baseRequest = {
+        recipientName: recipient.name,
+        recipientPhone: recipient.phone,
+        recipientEmail: recipient.email,
+        size: determineFoxpostSize(parcel)?.toUpperCase() || 'S',
+        cod: codAmount,
+        // Optional fields
+        refCode: parcel.references?.customerReference
+            ?.substring(0, 30)
+            .concat(`-${parcel.id.substring(0, 10)}`),
+        comment: parcel.handling?.fragile ? 'FRAGILE' : undefined,
+        fragile: parcel.handling?.fragile || false,
+    };
+    // HOME delivery includes address fields
+    if (isHomeDelivery) {
+        return {
+            ...baseRequest,
+            recipientCity: recipient.city,
+            recipientZip: recipient.zip,
+            recipientAddress: recipient.address,
+            recipientCountry: recipient.country,
+        };
+    }
+    // PICKUP_POINT delivery adds destination (locker/APM code)
+    if (delivery.method === 'PICKUP_POINT') {
+        const pickupPoint = delivery.pickupPoint;
+        return {
+            ...baseRequest,
+            destination: pickupPoint?.id || '',
+        };
+    }
+    return baseRequest;
+}
+/**
+ * Map canonical Parcel to Foxpost CreateParcelRequest
+ * Parcel contains complete shipping details (sender, recipient, weight, service, etc.)
+ *
+ * Handles both HOME delivery (full address) and PICKUP_POINT delivery (APM/locker)
+ */
+export function mapParcelToFoxpost(parcel, options = {}) {
+    const delivery = parcel.recipient.delivery;
+    const isHomeDelivery = delivery.method === 'HOME';
+    const recipientAddr = isHomeDelivery
+        ? delivery.address
+        : undefined;
+    const recipient = {
+        name: parcel.recipient.contact.name.substring(0, 150),
+        phone: parcel.recipient.contact.phone || "",
+        email: parcel.recipient.contact.email || "",
+        city: recipientAddr?.city?.substring(0, 25),
+        zip: recipientAddr?.postalCode,
+        address: recipientAddr?.street?.substring(0, 150),
+        country: recipientAddr?.country || "HU",
+    };
+    const foxpostRequest = {
+        recipientName: recipient.name,
+        recipientPhone: recipient.phone,
+        recipientEmail: recipient.email,
+        // HOME delivery includes address fields; APM leaves them undefined
+        ...(isHomeDelivery && {
+            recipientCity: recipient.city,
+            recipientZip: recipient.zip,
+            recipientAddress: recipient.address,
+            recipientCountry: recipient.country,
+        }),
+        size: determineFoxpostSize(parcel),
+        // Optional fields
+        refCode: parcel.references?.customerReference
+            ?.substring(0, 30)
+            .concat(`-${parcel.id.substring(0, 10)}`),
+        comment: parcel.handling?.fragile ? 'FRAGILE' : undefined,
+        fragile: parcel.handling?.fragile || false,
+    };
+    // For PICKUP_POINT delivery, add destination (locker/APM code)
+    if (!isHomeDelivery && delivery.method === 'PICKUP_POINT') {
+        const pickupPoint = delivery.pickupPoint;
+        if (pickupPoint?.id) {
+            foxpostRequest.destination = pickupPoint.id;
+        }
+    }
+    return foxpostRequest;
+}
+/**
+ * Map Foxpost tracking status code to canonical TrackingStatus
+ * Uses comprehensive status mapping from trackStatus.ts
+ * Unknown codes default to PENDING.
+ */
+export function mapFoxpostStatusToCanonical(foxpostStatus) {
+    const mapping = mapFoxpostStatusCode(foxpostStatus);
+    return mapping.canonical; // Safe cast: trackStatus map returns valid canonical values
+}
+/**
+ * Map Foxpost TrackDTO to canonical TrackingEvent
+ *
+ * Normalizes the Foxpost status code to a canonical TrackingStatus while preserving
+ * the original carrier-specific code in `carrierStatusCode` for debugging and carrier-specific logic.
+ */
+export function mapFoxpostTrackToCanonical(track) {
+    return {
+        timestamp: new Date(track.statusDate || new Date()),
+        status: mapFoxpostStatusToCanonical(track.status || "PENDING"),
+        carrierStatusCode: track.status || undefined,
+        description: track.longName || track.status || "Unknown status",
+        raw: track,
+    };
+}
+/**
+ * Map Foxpost TraceDTO (from new /api/tracking/{barcode} endpoint) to canonical TrackingEvent
+ * TraceDTO is returned in reverse chronological order (latest first) from the API
+ *
+ * Normalizes the Foxpost status code to a canonical TrackingStatus while preserving
+ * the original carrier-specific code in `carrierStatusCode`.
+ *
+ * Includes both English and Hungarian human-readable descriptions from the status map.
+ *
+ * Accepts both string and Date types for statusDate to support both raw API responses
+ * and validated Zod-parsed responses (which transform to Date).
+ *
+ * Example mapping:
+ * - Foxpost "CREATE" -> canonical "PENDING" (carrierStatusCode: "CREATE", description: "Order created")
+ * - Foxpost "HDINTRANSIT" -> canonical "OUT_FOR_DELIVERY" (carrierStatusCode: "HDINTRANSIT", description: "Out for home delivery")
+ * - Foxpost "RECEIVE" -> canonical "DELIVERED" (carrierStatusCode: "RECEIVE", description: "Delivered to recipient")
+ */
+export function mapFoxpostTraceToCanonical(trace) {
+    const statusDate = typeof trace.statusDate === 'string'
+        ? new Date(trace.statusDate)
+        : trace.statusDate;
+    const statusCode = trace.status || "PENDING";
+    const statusMapping = mapFoxpostStatusCode(statusCode);
+    // Prefer mapped human description; fall back to API data if available
+    const humanDescription = statusMapping.human_en
+        || (trace.longName || trace.shortName || null)
+        || `Foxpost: ${statusCode}`;
+    const humanDescriptionHu = statusMapping.human_hu || null;
+    return {
+        timestamp: statusDate || new Date(),
+        status: mapFoxpostStatusToCanonical(statusCode),
+        carrierStatusCode: statusCode || undefined,
+        description: humanDescription,
+        descriptionLocalLanguage: humanDescriptionHu || undefined,
+        raw: trace,
+    };
+}
+/**
+ * Map canonical Parcel to Foxpost carrier-specific parcel (HD or APM)
+ * Discriminates based on Delivery type in the parcel
+ *
+ * @param parcel - Canonical parcel with full shipping details
+ * @param options - Additional mapping options (COD, comment, etc.)
+ * @returns FoxpostParcelHD | FoxpostParcelAPM with type discriminator set
+ */
+export function mapParcelToFoxpostCarrierType(parcel, options = {}) {
+    const recipient = parcel.recipient;
+    const delivery = recipient.delivery;
+    // Determine parcel size
+    const size = (determineFoxpostSize(parcel) || 's').toUpperCase();
+    // COD amount from parcel.cod or options override
+    const codAmount = options.cod ?? parcel.cod?.amount.amount ?? 0;
+    // Fragile from options or parcel.handling
+    const isFragile = options.fragile ?? parcel.handling?.fragile ?? false;
+    // If delivery is PICKUP_POINT, create APM parcel
+    if (delivery.method === 'PICKUP_POINT') {
+        const apmParcel = {
+            type: 'APM',
+            cod: codAmount,
+            comment: options.comment,
+            destination: delivery.pickupPoint.id,
+            recipientEmail: recipient.contact.email || '',
+            recipientName: recipient.contact.name.substring(0, 150),
+            recipientPhone: recipient.contact.phone || '',
+            refCode: parcel.references?.customerReference?.substring(0, 30),
+            size,
+        };
+        return apmParcel;
+    }
+    // Otherwise (HOME delivery), create HD parcel
+    const homeDelivery = delivery;
+    const recipientAddr = homeDelivery.address;
+    const hdParcel = {
+        type: 'HD',
+        cod: codAmount,
+        comment: options.comment,
+        deliveryNote: options.deliveryNote || homeDelivery.instructions,
+        fragile: isFragile,
+        label: false, // Default: Foxpost prints label for B2B, not for C2C
+        recipientAddress: `${recipientAddr.street || ''}, ${recipientAddr.postalCode || ''} ${recipientAddr.city || ''}`.trim(),
+        recipientCity: recipientAddr.city,
+        recipientCountry: recipientAddr.country,
+        recipientEmail: recipient.contact.email || '',
+        recipientName: recipient.contact.name.substring(0, 150),
+        recipientPhone: recipient.contact.phone || '',
+        recipientZip: recipientAddr.postalCode,
+        refCode: parcel.references?.customerReference?.substring(0, 30),
+        size,
+    };
+    return hdParcel;
+}

package/dist/mappers/trackStatus.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Foxpost Tracking Status Map
+ *
+ * Comprehensive mapping of Foxpost status codes to:
+ * 1. Canonical tracking status (for normalized processing)
+ * 2. Human-readable descriptions in English and Hungarian
+ *
+ * The canonical status is used for generic processing, filtering, and integrator logic,
+ * while the human descriptions provide detailed information about the shipment state.
+ *
+ * Source: Foxpost OpenAPI tracking documentation and operational codes
+ */
+import type { TrackingStatus } from "@shopickup/core";
+export interface FoxpostStatusMapping {
+    /** Canonical status across all carriers */
+    canonical: TrackingStatus;
+    /** Human-readable description in English */
+    human_en?: string;
+    /** Human-readable description in Hungarian */
+    human_hu?: string;
+    /** Category hint for interpretation */
+    type?: 'locker' | 'courier' | 'facility' | 'technical';
+}
+/**
+ * Complete Foxpost status code to canonical mapping
+ *
+ * Key characteristics:
+ * - All Foxpost codes are covered (37 codes)
+ * - Unknown codes default to "UNKNOWN" with fallback description
+ * - Each code has English and Hungarian descriptions from Foxpost docs
+ * - Technical codes (CREATE, SLOTCHANGE, etc.) are marked with type: 'technical'
+ */
+export declare const FOXPOST_STATUS_MAP: Record<string, FoxpostStatusMapping>;
+/**
+ * Map Foxpost status code to canonical and human descriptions
+ *
+ * @param code Foxpost status code (e.g., "OPERIN", "HDINTRANSIT")
+ * @returns Mapping with canonical status and human descriptions (EN + HU)
+ *
+ * Unknown codes default to PENDING canonical status with fallback description.
+ *
+ * @example
+ * const mapping = mapFoxpostStatusCode("OPERIN");
+ * // { canonical: "IN_TRANSIT", human_en: "Arrived at locker", human_hu: "Automatában megérkezett" }
+ *
+ * const unknown = mapFoxpostStatusCode("FOOBAR");
+ * // { canonical: "PENDING", human_en: "Foxpost: FOOBAR", human_hu: undefined }
+ */
+export declare function mapFoxpostStatusCode(code: string): FoxpostStatusMapping;
+/**
+ * Get human-readable description in specified language
+ *
+ * @param code Foxpost status code
+ * @param language "en" for English, "hu" for Hungarian
+ * @returns Human-readable description
+ */
+export declare function getFoxpostStatusDescription(code: string, language?: "en" | "hu"): string;
+//# sourceMappingURL=trackStatus.d.ts.map

package/dist/mappers/trackStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackStatus.d.ts","sourceRoot":"","sources":["../../src/mappers/trackStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,SAAS,EAAE,cAAc,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;CACxD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CA0OnE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAcvE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,IAAI,GAAG,IAAW,GAC3B,MAAM,CAQR"}

package/dist/mappers/trackStatus.js

@@ -0,0 +1,290 @@
+/**
+ * Foxpost Tracking Status Map
+ *
+ * Comprehensive mapping of Foxpost status codes to:
+ * 1. Canonical tracking status (for normalized processing)
+ * 2. Human-readable descriptions in English and Hungarian
+ *
+ * The canonical status is used for generic processing, filtering, and integrator logic,
+ * while the human descriptions provide detailed information about the shipment state.
+ *
+ * Source: Foxpost OpenAPI tracking documentation and operational codes
+ */
+/**
+ * Complete Foxpost status code to canonical mapping
+ *
+ * Key characteristics:
+ * - All Foxpost codes are covered (37 codes)
+ * - Unknown codes default to "UNKNOWN" with fallback description
+ * - Each code has English and Hungarian descriptions from Foxpost docs
+ * - Technical codes (CREATE, SLOTCHANGE, etc.) are marked with type: 'technical'
+ */
+export const FOXPOST_STATUS_MAP = {
+    // === Locker/APM Operations ===
+    CREATE: {
+        canonical: "PENDING",
+        human_en: "Order created",
+        human_hu: "Rendelés létrehozva",
+        type: "locker",
+    },
+    OPERIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at locker",
+        human_hu: "Automatában megérkezett",
+        type: "locker",
+    },
+    OPEROUT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Removed from locker / Out for delivery",
+        human_hu: "Automatából kivéve / Kiszállítás",
+        type: "locker",
+    },
+    RECEIVE: {
+        canonical: "DELIVERED",
+        human_en: "Delivered to recipient",
+        human_hu: "Átvéve",
+        type: "locker",
+    },
+    // === Return Operations ===
+    RETURN: {
+        canonical: "RETURNED",
+        human_en: "Returned to sender",
+        human_hu: "Visszaküldésre került",
+        type: "facility",
+    },
+    REDIRECT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Redirected to new destination",
+        human_hu: "Átirányítva új célhelyre",
+        type: "facility",
+    },
+    BACKTOSENDER: {
+        canonical: "RETURNED",
+        human_en: "Returned to sender",
+        human_hu: "Szállító felé visszaküldve",
+        type: "facility",
+    },
+    RESENT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Resent to new destination",
+        human_hu: "Újra küldve új célhelyre",
+        type: "facility",
+    },
+    // === Facility Sorting Operations ===
+    SORTIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at sorting facility",
+        human_hu: "Rendezőközpontba megérkezett",
+        type: "facility",
+    },
+    SORTOUT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Left sorting facility",
+        human_hu: "Rendezőközpontból elküldve",
+        type: "facility",
+    },
+    MPSIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at parcel hub",
+        human_hu: "Csomagközpontba megérkezett",
+        type: "facility",
+    },
+    C2CIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at customer collection point",
+        human_hu: "Ügyfél felvevőpontba megérkezett",
+        type: "facility",
+    },
+    C2BIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at business collection point",
+        human_hu: "Üzleti felvevőpontba megérkezett",
+        type: "facility",
+    },
+    INWAREHOUSE: {
+        canonical: "IN_TRANSIT",
+        human_en: "In warehouse",
+        human_hu: "Raktárban van",
+        type: "facility",
+    },
+    // === Home Delivery Operations ===
+    HDSENT: {
+        canonical: "OUT_FOR_DELIVERY",
+        human_en: "Home delivery sent",
+        human_hu: "Házhozszállítás küldve",
+        type: "courier",
+    },
+    HDINTRANSIT: {
+        canonical: "OUT_FOR_DELIVERY",
+        human_en: "Out for home delivery",
+        human_hu: "Házhoz szállítás alatt",
+        type: "courier",
+    },
+    HDDEPO: {
+        canonical: "IN_TRANSIT",
+        human_en: "At home delivery depot",
+        human_hu: "Kiszállítási depoban",
+        type: "facility",
+    },
+    HDCOURIER: {
+        canonical: "OUT_FOR_DELIVERY",
+        human_en: "With courier for delivery",
+        human_hu: "Futárnál szállításra",
+        type: "courier",
+    },
+    HDHUBIN: {
+        canonical: "IN_TRANSIT",
+        human_en: "Arrived at delivery hub",
+        human_hu: "Szállítási csomópontra megérkezett",
+        type: "facility",
+    },
+    HDHUBOUT: {
+        canonical: "OUT_FOR_DELIVERY",
+        human_en: "Left delivery hub",
+        human_hu: "Szállítási csomópontból elküldve",
+        type: "facility",
+    },
+    HDRECEIVE: {
+        canonical: "DELIVERED",
+        human_en: "Delivered by home delivery",
+        human_hu: "Házhoz szállítva",
+        type: "courier",
+    },
+    HDRETURN: {
+        canonical: "RETURNED",
+        human_en: "Returned from home delivery",
+        human_hu: "Házhoz szállítás visszatérült",
+        type: "courier",
+    },
+    // === Exception States ===
+    OVERTIMEOUT: {
+        canonical: "EXCEPTION",
+        human_en: "Overtime out (delivery exceeded time limit)",
+        human_hu: "Túlóra lejárt",
+        type: "technical",
+    },
+    OVERTIMED: {
+        canonical: "EXCEPTION",
+        human_en: "Overtime (delivery delayed)",
+        human_hu: "Túlóra (késedelem)",
+        type: "technical",
+    },
+    HDUNDELIVERABLE: {
+        canonical: "EXCEPTION",
+        human_en: "Undeliverable (home delivery failed)",
+        human_hu: "Nem szállítható (házhoz szállítás sikertelen)",
+        type: "courier",
+    },
+    MISSORT: {
+        canonical: "EXCEPTION",
+        human_en: "Missorted - rerouted",
+        human_hu: "Hibásan rendezett - átirányított",
+        type: "technical",
+    },
+    EMPTYSLOT: {
+        canonical: "EXCEPTION",
+        human_en: "No locker slot available",
+        human_hu: "Nincs szabad automatahely",
+        type: "locker",
+    },
+    BACKLOGINFULL: {
+        canonical: "EXCEPTION",
+        human_en: "Backlog - facility at capacity",
+        human_hu: "Feldolgozási várakozási sor teljes",
+        type: "facility",
+    },
+    BACKLOGINFAIL: {
+        canonical: "EXCEPTION",
+        human_en: "Backlog failed - retry needed",
+        human_hu: "Feldolgozási sor sikertelen",
+        type: "technical",
+    },
+    // === Collection/Handoff Operations ===
+    COLLECTSENT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Collect shipment sent",
+        human_hu: "Gyűjtőszállítmány küldve",
+        type: "facility",
+    },
+    COLLECTED: {
+        canonical: "DELIVERED",
+        human_en: "Collected from sender",
+        human_hu: "Feladótól összeszedve",
+        type: "facility",
+    },
+    // === Slot/Redirect Operations ===
+    SLOTCHANGE: {
+        canonical: "IN_TRANSIT",
+        human_en: "Locker slot changed",
+        human_hu: "Automatahely módosult",
+        type: "technical",
+    },
+    WBXREDIRECT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Redirected via WBX",
+        human_hu: "WBX-en keresztül átirányított",
+        type: "facility",
+    },
+    PREREDIRECT: {
+        canonical: "IN_TRANSIT",
+        human_en: "Pre-redirect (staged for redirection)",
+        human_hu: "Előátirányítás (átirányításra előkészítve)",
+        type: "technical",
+    },
+    // === Final Delivery State ===
+    RETURNED: {
+        canonical: "DELIVERED",
+        human_en: "Returned (delivered back to sender)",
+        human_hu: "Visszaküldve (feladónak szállítva)",
+        type: "facility",
+    },
+    // === Preparation/Technical ===
+    PREPAREDFORPD: {
+        canonical: "IN_TRANSIT",
+        human_en: "Prepared for home delivery",
+        human_hu: "Házhoz szállításra előkészítve",
+        type: "technical",
+    },
+};
+/**
+ * Map Foxpost status code to canonical and human descriptions
+ *
+ * @param code Foxpost status code (e.g., "OPERIN", "HDINTRANSIT")
+ * @returns Mapping with canonical status and human descriptions (EN + HU)
+ *
+ * Unknown codes default to PENDING canonical status with fallback description.
+ *
+ * @example
+ * const mapping = mapFoxpostStatusCode("OPERIN");
+ * // { canonical: "IN_TRANSIT", human_en: "Arrived at locker", human_hu: "Automatában megérkezett" }
+ *
+ * const unknown = mapFoxpostStatusCode("FOOBAR");
+ * // { canonical: "PENDING", human_en: "Foxpost: FOOBAR", human_hu: undefined }
+ */
+export function mapFoxpostStatusCode(code) {
+    const mapping = FOXPOST_STATUS_MAP[code];
+    if (mapping) {
+        return mapping;
+    }
+    // Fallback for unknown codes: map to PENDING with fallback description
+    return {
+        canonical: "PENDING",
+        human_en: `Foxpost: ${code}`,
+        human_hu: undefined,
+        type: "technical",
+    };
+}
+/**
+ * Get human-readable description in specified language
+ *
+ * @param code Foxpost status code
+ * @param language "en" for English, "hu" for Hungarian
+ * @returns Human-readable description
+ */
+export function getFoxpostStatusDescription(code, language = "en") {
+    const mapping = mapFoxpostStatusCode(code);
+    if (language === "hu") {
+        return mapping.human_hu ?? mapping.human_en ?? `Foxpost: ${code}`;
+    }
+    return mapping.human_en ?? `Foxpost: ${code}`;
+}