@shopickup/adapters-foxpost 0.0.1

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+import { CarrierError } from "@shopickup/core";
+/**
+ * Translate Foxpost errors to structured CarrierError
+ *
+ * Supports errors from any HTTP client implementation:
+ * - axios
+ * - node-fetch
+ * - undici
+ * - custom HTTP clients
+ * - network errors
+ *
+ * Error categorization:
+ * - 400: Validation (client error, don't retry)
+ * - 401/403: Auth (authentication failure, check credentials)
+ * - 429: RateLimit (rate limited, retry with backoff)
+ * - 5xx: Transient (server error, retry)
+ * - Network: Transient (connection issue, retry)
+ */
+export declare function translateFoxpostError(error: unknown): CarrierError;
+/**
+ * Sanitize an HTTP response object for safe logging
+ * Removes sensitive headers (Authorization, Api-key, etc.) before serialization
+ *
+ * Safely handles various HTTP client response shapes:
+ * - axios: { data, status, headers, config }
+ * - fetch: { status, headers, body }
+ * - undici: { status, headers, body }
+ * - custom: any object with headers property
+ *
+ * @param response HTTP response object (may be from any HTTP client)
+ * @returns Sanitized copy safe for logging (original not modified)
+ */
+export declare function sanitizeResponseForLog(response: unknown): unknown;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA0C,MAAM,iBAAiB,CAAC;AAiFvF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAiElE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAqCjE"}

package/dist/errors.js

@@ -0,0 +1,165 @@
+import { CarrierError, sanitizeHeadersForLog } from "@shopickup/core";
+/**
+ * Foxpost-specific error code translations
+ */
+const FoxpostErrorCodes = {
+    WRONG_USERNAME_OR_PASSWORD: {
+        category: "Auth",
+        message: "Invalid Foxpost credentials",
+    },
+    INVALID_APM_ID: {
+        category: "Validation",
+        message: "Invalid APM (locker) ID",
+    },
+    INVALID_RECIPIENT: {
+        category: "Validation",
+        message: "Invalid recipient information",
+    },
+    INVALID_ADDRESS: {
+        category: "Validation",
+        message: "Invalid address provided",
+    },
+};
+/**
+ * Extract HTTP status code from error object
+ * Works with errors from different HTTP clients (axios, fetch, undici, custom)
+ *
+ * Supports common error shapes:
+ * - axios: error.response.status
+ * - fetch: error.status (when wrapped)
+ * - undici: error.statusCode
+ * - generic: error.response?.status or error.status
+ */
+function extractHttpStatus(error) {
+    const anyErr = error;
+    // Try multiple common locations for HTTP status
+    return (anyErr?.response?.status ?? // axios, fetch-like wrappers
+        anyErr?.status ?? // direct status property
+        anyErr?.statusCode ?? // undici, some node wrappers
+        anyErr?.code === 'ECONNREFUSED' ? undefined : undefined // network error, not HTTP status
+    );
+}
+/**
+ * Extract response body from error object
+ * Works with errors from different HTTP clients
+ *
+ * Supports common error shapes:
+ * - axios: error.response.data
+ * - fetch: error.response?.json() or error.data
+ * - undici: error.body or error.data
+ */
+function extractResponseBody(error) {
+    const anyErr = error;
+    return (anyErr?.response?.data ?? // axios, generic response objects
+        anyErr?.data ?? // direct data property (undici, fetch wrappers)
+        anyErr?.body ?? // node-fetch, undici
+        anyErr?.response // fallback to whole response
+    );
+}
+/**
+ * Extract error code from response body
+ * Looks for common field names across different APIs
+ */
+function extractErrorCode(responseBody) {
+    const body = responseBody;
+    return (body?.error ?? // common JSON API error field
+        body?.code ?? // error code field
+        body?.errorCode ?? // camelCase variant
+        body?.error_code // snake_case variant
+    );
+}
+/**
+ * Translate Foxpost errors to structured CarrierError
+ *
+ * Supports errors from any HTTP client implementation:
+ * - axios
+ * - node-fetch
+ * - undici
+ * - custom HTTP clients
+ * - network errors
+ *
+ * Error categorization:
+ * - 400: Validation (client error, don't retry)
+ * - 401/403: Auth (authentication failure, check credentials)
+ * - 429: RateLimit (rate limited, retry with backoff)
+ * - 5xx: Transient (server error, retry)
+ * - Network: Transient (connection issue, retry)
+ */
+export function translateFoxpostError(error) {
+    const anyErr = error;
+    // Extract common error properties in a client-agnostic way
+    const status = extractHttpStatus(error);
+    const responseBody = extractResponseBody(error);
+    const errorCode = extractErrorCode(responseBody) || (typeof status === 'number' ? `HTTP_${status}` : undefined);
+    const errorMapping = errorCode ? FoxpostErrorCodes[errorCode] : undefined;
+    // Construct metadata with all available context
+    const meta = {
+        carrierCode: errorCode,
+        raw: responseBody ?? anyErr,
+    };
+    // Route by HTTP status code
+    if (typeof status === 'number') {
+        if (status === 400) {
+            return new CarrierError(`Validation error: ${errorMapping?.message || responseBody?.error || "Bad request"}`, "Validation", meta);
+        }
+        if (status === 401 || status === 403) {
+            return new CarrierError("Foxpost credentials invalid", "Auth", meta);
+        }
+        if (status === 429) {
+            return new CarrierError("Foxpost rate limit exceeded", "RateLimit", { ...meta, retryAfterMs: 60000 });
+        }
+        if (status >= 500) {
+            return new CarrierError("Foxpost server error", "Transient", meta);
+        }
+    }
+    // Network error (Error instance with no HTTP status)
+    if (error instanceof Error) {
+        return new CarrierError(`Foxpost connection error: ${error.message}`, "Transient", { raw: anyErr });
+    }
+    // Unknown error shape
+    return new CarrierError("Unknown Foxpost error", "Permanent", { raw: anyErr });
+}
+/**
+ * Sanitize an HTTP response object for safe logging
+ * Removes sensitive headers (Authorization, Api-key, etc.) before serialization
+ *
+ * Safely handles various HTTP client response shapes:
+ * - axios: { data, status, headers, config }
+ * - fetch: { status, headers, body }
+ * - undici: { status, headers, body }
+ * - custom: any object with headers property
+ *
+ * @param response HTTP response object (may be from any HTTP client)
+ * @returns Sanitized copy safe for logging (original not modified)
+ */
+export function sanitizeResponseForLog(response) {
+    if (!response || typeof response !== 'object') {
+        return response;
+    }
+    const resp = response;
+    // Create a shallow copy to avoid modifying original
+    const sanitized = {};
+    for (const [key, value] of Object.entries(resp)) {
+        // Always skip request body (should not be in response, but be safe)
+        if (key === 'body' && typeof value === 'string' && value.length > 10000) {
+            sanitized[key] = '[Large binary or text body - truncated for logging]';
+            continue;
+        }
+        // Sanitize headers property if present
+        if (key === 'headers' && typeof value === 'object') {
+            sanitized[key] = sanitizeHeadersForLog(value);
+            continue;
+        }
+        // Sanitize config.headers (axios pattern)
+        if (key === 'config' && typeof value === 'object') {
+            sanitized[key] = {
+                ...value,
+                headers: sanitizeHeadersForLog(value?.headers),
+            };
+            continue;
+        }
+        // Include all other properties as-is
+        sanitized[key] = value;
+    }
+    return sanitized;
+}

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Foxpost Carrier Adapter
+ * Implements the CarrierAdapter interface for Foxpost logistics
+ */
+import type { CarrierAdapter, Capability, AdapterContext, CreateParcelRequest, CreateParcelsRequest, TrackingRequest, RatesRequest, CreateParcelsResponse, CreateLabelRequest, CreateLabelResponse, CreateLabelsRequest, CreateLabelsResponse, CarrierResource, TrackingUpdate, FetchPickupPointsRequest, FetchPickupPointsResponse } from "@shopickup/core";
+/**
+ * FoxpostAdapter
+ *
+ * Foxpost (hu-foxpost) is a major Hungarian logistics carrier.
+ *
+ * Capabilities supported:
+ * - CREATE_PARCEL: Create parcels directly
+ * - CREATE_PARCELS: Batch create multiple parcels
+ * - CREATE_LABEL: Generate PDF labels for parcels
+ * - TRACK: Track parcels by barcode
+ * - TEST_MODE_SUPPORTED: Can switch to test API for sandbox testing
+ *
+ * Test API:
+ * - Production: https://webapi.foxpost.hu
+ * - Test/Sandbox: https://webapi-test.foxpost.hu
+ * - Pass options.useTestApi = true in request to switch to test endpoint for that call
+ * - Test API requires separate test credentials
+ *
+ * Notes:
+ * - Foxpost does NOT have a shipment concept; parcels are created directly
+ * - Labels are generated per parcel
+ * - Tracking available via barcode (FoxWeb barcode format: CLFOX...)
+ * - createLabel does not support per-call test mode (no request object in interface)
+ */
+export declare class FoxpostAdapter implements CarrierAdapter {
+    readonly id = "hu-foxpost";
+    readonly displayName = "Foxpost Hungary";
+    readonly capabilities: Capability[];
+    readonly requires: {
+        createLabel: "CREATE_PARCEL"[];
+    };
+    private prodBaseUrl;
+    private testBaseUrl;
+    private resolveBaseUrl;
+    constructor(baseUrl?: string);
+    /**
+     * Create a parcel in Foxpost
+     *
+     * Note: Shipper information is not sent to Foxpost API.
+     * Foxpost derives the shipper from the API key's account settings.
+     * We require shipper in the core Parcel type for consistency across adapters.
+     *
+     * Maps canonical Parcel to Foxpost CreateParcelRequest (and carrier-specific type)
+     * Returns the parcel barcode as carrierId
+     */
+    createParcel(req: CreateParcelRequest, ctx: AdapterContext): Promise<CarrierResource>;
+    /**
+     * Create multiple parcels in one call
+     * Maps canonical Parcel array to Foxpost CreateParcelRequest and calls the
+     * Foxpost batch endpoint which accepts an array. Returns per-item CarrierResource
+     * so callers can handle partial failures.
+     *
+     * Validates both the incoming parcels and the mapped carrier-specific payloads.
+     *
+     * @returns CreateParcelsResponse with summary and per-item results
+     */
+    createParcels(req: CreateParcelsRequest, ctx: AdapterContext): Promise<CreateParcelsResponse>;
+    /**
+     * Create a label (generate PDF) for a parcel
+     *
+     * @param req CreateLabelRequest with parcelCarrierId (Foxpost barcode)
+     * @param ctx AdapterContext with HTTP client and logger
+     * @returns LabelResult with file mapping and page range
+     */
+    createLabel(req: CreateLabelRequest, ctx: AdapterContext): Promise<CreateLabelResponse>;
+    /**
+     * Create labels for multiple parcels in one batch call
+     *
+     * Generates a single PDF with all requested labels using Foxpost POST /api/label/{pageSize}
+     * Returns per-item results for tracking success/failure of each label
+     *
+     * @param req CreateLabelsRequest with array of parcelCarrierIds
+     * @param ctx AdapterContext with HTTP client and logger
+     * @returns CreateLabelsResponse with per-item results and summary
+     */
+    createLabels(req: CreateLabelsRequest, ctx: AdapterContext): Promise<CreateLabelsResponse>;
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't support voiding labels
+     */
+    voidLabel(_labelId: string, _ctx: AdapterContext): Promise<CarrierResource>;
+    /**
+     * Track a parcel by its clFoxId or uniqueBarcode using the new GET /api/tracking/{barcode} endpoint
+     *
+     * Returns normalized tracking information with all available traces in reverse chronological order
+     *
+     * To use test API, pass in request as:
+     * { trackingNumber: barcode, credentials: {...}, options?: { useTestApi: true } }
+     */
+    track(req: TrackingRequest, ctx: AdapterContext): Promise<TrackingUpdate>;
+    /**
+     * Fetch list of Foxpost pickup points (APMs)
+     *
+     * Fetches the public JSON feed from https://cdn.foxpost.hu/foxplus.json
+     * which is updated hourly and contains all active APM locations.
+     *
+     * No authentication is required as this is a public feed.
+     *
+     * @param req FetchPickupPointsRequest (optional filters)
+     * @param ctx AdapterContext with HTTP client
+     * @returns FetchPickupPointsResponse with normalized pickup points
+     */
+    fetchPickupPoints(req: FetchPickupPointsRequest, ctx: AdapterContext): Promise<FetchPickupPointsResponse>;
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't support pickup requests
+     */
+    requestPickup(_req: any, _ctx: AdapterContext): Promise<CarrierResource>;
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't expose rate quotes
+     */
+    getRates(_req: RatesRequest, _ctx: AdapterContext): Promise<any>;
+}
+export default FoxpostAdapter;
+export { safeValidateTrackingRequest, safeValidateFoxpostTracking, validateFoxpostTracking, safeValidateFoxpostCredentials, validateFoxpostCredentials, type FoxpostTracking, type FoxpostTrace, type FoxpostTrackDTO, } from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,iBAAiB,CAAC;AAgBzB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,cAAe,YAAW,cAAc;IACnD,QAAQ,CAAC,EAAE,gBAAgB;IAC3B,QAAQ,CAAC,WAAW,qBAAqB;IAEzC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,CAOjC;IAGF,QAAQ,CAAC,QAAQ;;MAEf;IAEF,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,cAAc,CAAiB;gBAE3B,OAAO,GAAE,MAAoC;IAMzD;;;;;;;;;OASG;IACG,YAAY,CAChB,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,eAAe,CAAC;IAM3B;;;;;;;;;OASG;IACG,aAAa,CACjB,GAAG,EAAE,oBAAoB,EACzB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,qBAAqB,CAAC;IAIjC;;;;;;OAMG;IACG,WAAW,CACf,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,mBAAmB,CAAC;IAI/B;;;;;;;;;OASG;IACG,YAAY,CAChB,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,oBAAoB,CAAC;IAIhC;;OAEG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,eAAe,CAAC;IAI3B;;;;;;;OAOG;IACG,KAAK,CACT,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,cAAc,CAAC;IAI1B;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,yBAAyB,CAAC;IAIrC;;OAEG;IACG,aAAa,CACjB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,eAAe,CAAC;IAI3B;;OAEG;IACG,QAAQ,CACZ,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,GAAG,CAAC;CAGhB;AAED,eAAe,cAAc,CAAC;AAG9B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,uBAAuB,EACvB,8BAA8B,EAC9B,0BAA0B,EAC1B,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,151 @@
+/**
+ * Foxpost Carrier Adapter
+ * Implements the CarrierAdapter interface for Foxpost logistics
+ */
+import { Capabilities, NotImplementedError } from "@shopickup/core";
+import { createParcel as createParcelImpl, createParcels as createParcelsImpl, createLabel as createLabelImpl, createLabels as createLabelsImpl, track as trackImpl, fetchPickupPoints as fetchPickupPointsImpl, } from './capabilities/index.js';
+import { createResolveBaseUrl } from './utils/resolveBaseUrl.js';
+/**
+ * FoxpostAdapter
+ *
+ * Foxpost (hu-foxpost) is a major Hungarian logistics carrier.
+ *
+ * Capabilities supported:
+ * - CREATE_PARCEL: Create parcels directly
+ * - CREATE_PARCELS: Batch create multiple parcels
+ * - CREATE_LABEL: Generate PDF labels for parcels
+ * - TRACK: Track parcels by barcode
+ * - TEST_MODE_SUPPORTED: Can switch to test API for sandbox testing
+ *
+ * Test API:
+ * - Production: https://webapi.foxpost.hu
+ * - Test/Sandbox: https://webapi-test.foxpost.hu
+ * - Pass options.useTestApi = true in request to switch to test endpoint for that call
+ * - Test API requires separate test credentials
+ *
+ * Notes:
+ * - Foxpost does NOT have a shipment concept; parcels are created directly
+ * - Labels are generated per parcel
+ * - Tracking available via barcode (FoxWeb barcode format: CLFOX...)
+ * - createLabel does not support per-call test mode (no request object in interface)
+ */
+export class FoxpostAdapter {
+    id = "hu-foxpost";
+    displayName = "Foxpost Hungary";
+    capabilities = [
+        Capabilities.CREATE_PARCEL,
+        Capabilities.CREATE_PARCELS,
+        Capabilities.CREATE_LABEL,
+        Capabilities.TRACK,
+        Capabilities.LIST_PICKUP_POINTS,
+        Capabilities.TEST_MODE_SUPPORTED,
+    ];
+    // Foxpost doesn't require close before label
+    requires = {
+        createLabel: [Capabilities.CREATE_PARCEL],
+    };
+    prodBaseUrl = "https://webapi.foxpost.hu";
+    testBaseUrl = "https://webapi-test.foxpost.hu";
+    resolveBaseUrl;
+    constructor(baseUrl = "https://webapi.foxpost.hu") {
+        this.prodBaseUrl = "https://webapi.foxpost.hu";
+        this.testBaseUrl = "https://webapi-test.foxpost.hu";
+        this.resolveBaseUrl = createResolveBaseUrl(this.prodBaseUrl, this.testBaseUrl);
+    }
+    /**
+     * Create a parcel in Foxpost
+     *
+     * Note: Shipper information is not sent to Foxpost API.
+     * Foxpost derives the shipper from the API key's account settings.
+     * We require shipper in the core Parcel type for consistency across adapters.
+     *
+     * Maps canonical Parcel to Foxpost CreateParcelRequest (and carrier-specific type)
+     * Returns the parcel barcode as carrierId
+     */
+    async createParcel(req, ctx) {
+        return createParcelImpl(req, ctx, (batchReq, batchCtx) => this.createParcels(batchReq, batchCtx));
+    }
+    /**
+     * Create multiple parcels in one call
+     * Maps canonical Parcel array to Foxpost CreateParcelRequest and calls the
+     * Foxpost batch endpoint which accepts an array. Returns per-item CarrierResource
+     * so callers can handle partial failures.
+     *
+     * Validates both the incoming parcels and the mapped carrier-specific payloads.
+     *
+     * @returns CreateParcelsResponse with summary and per-item results
+     */
+    async createParcels(req, ctx) {
+        return createParcelsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    /**
+     * Create a label (generate PDF) for a parcel
+     *
+     * @param req CreateLabelRequest with parcelCarrierId (Foxpost barcode)
+     * @param ctx AdapterContext with HTTP client and logger
+     * @returns LabelResult with file mapping and page range
+     */
+    async createLabel(req, ctx) {
+        return createLabelImpl(req, ctx, this.resolveBaseUrl);
+    }
+    /**
+     * Create labels for multiple parcels in one batch call
+     *
+     * Generates a single PDF with all requested labels using Foxpost POST /api/label/{pageSize}
+     * Returns per-item results for tracking success/failure of each label
+     *
+     * @param req CreateLabelsRequest with array of parcelCarrierIds
+     * @param ctx AdapterContext with HTTP client and logger
+     * @returns CreateLabelsResponse with per-item results and summary
+     */
+    async createLabels(req, ctx) {
+        return createLabelsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't support voiding labels
+     */
+    async voidLabel(_labelId, _ctx) {
+        throw new NotImplementedError("VOID_LABEL", this.id);
+    }
+    /**
+     * Track a parcel by its clFoxId or uniqueBarcode using the new GET /api/tracking/{barcode} endpoint
+     *
+     * Returns normalized tracking information with all available traces in reverse chronological order
+     *
+     * To use test API, pass in request as:
+     * { trackingNumber: barcode, credentials: {...}, options?: { useTestApi: true } }
+     */
+    async track(req, ctx) {
+        return trackImpl(req, ctx, this.resolveBaseUrl);
+    }
+    /**
+     * Fetch list of Foxpost pickup points (APMs)
+     *
+     * Fetches the public JSON feed from https://cdn.foxpost.hu/foxplus.json
+     * which is updated hourly and contains all active APM locations.
+     *
+     * No authentication is required as this is a public feed.
+     *
+     * @param req FetchPickupPointsRequest (optional filters)
+     * @param ctx AdapterContext with HTTP client
+     * @returns FetchPickupPointsResponse with normalized pickup points
+     */
+    async fetchPickupPoints(req, ctx) {
+        return fetchPickupPointsImpl(req, ctx);
+    }
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't support pickup requests
+     */
+    async requestPickup(_req, _ctx) {
+        throw new NotImplementedError("PICKUP", this.id);
+    }
+    /**
+     * NOT IMPLEMENTED: Foxpost doesn't expose rate quotes
+     */
+    async getRates(_req, _ctx) {
+        throw new NotImplementedError("RATES", this.id);
+    }
+}
+export default FoxpostAdapter;
+// Export validation helpers for use in external code (e.g., dev-server)
+export { safeValidateTrackingRequest, safeValidateFoxpostTracking, validateFoxpostTracking, safeValidateFoxpostCredentials, validateFoxpostCredentials, } from './validation.js';

package/dist/mappers/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Mappers for Foxpost adapter
+ * Converts between canonical Shopickup types and Foxpost API types
+ */
+import type { Parcel, TrackingEvent } from "@shopickup/core";
+import type { CreateParcelRequest as FoxpostParcelRequest, TrackDTO as FoxpostTrackDTO, TraceDTO as FoxpostTraceDTO } from '../types/generated.js';
+import type { FoxpostParcel, FoxCreateParcelRequestItem } from '../validation.js';
+declare const FOXPOST_SIZES: readonly ["xs", "s", "m", "l", "xl"];
+type FoxpostSize = typeof FOXPOST_SIZES[number];
+/**
+ * Map canonical Address (from Parcel.sender or Parcel.recipient) to Foxpost address format
+ */
+export declare function mapAddressToFoxpost(addr: {
+    name: string;
+    street: string;
+    city: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+    email?: string;
+}): {
+    name: string;
+    phone: string;
+    email: string;
+    city?: string;
+    zip?: string;
+    address?: string;
+    country: string;
+};
+/**
+ * Determine parcel size based on dimensions or weight
+ * Foxpost sizes: xs, s, m, l, xl
+ */
+export declare function determineFoxpostSize(parcel: Parcel): FoxpostSize | undefined;
+/**
+ * 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 declare function mapParcelToFoxpostRequest(parcel: Parcel, options?: {
+    isWeb?: boolean;
+    isRedirect?: boolean;
+}): FoxCreateParcelRequestItem;
+/**
+ * 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 declare function mapParcelToFoxpost(parcel: Parcel, options?: {
+    isWeb?: boolean;
+    isRedirect?: boolean;
+}): FoxpostParcelRequest & {
+    destination?: string;
+};
+/**
+ * Map Foxpost tracking status code to canonical TrackingStatus
+ * Uses comprehensive status mapping from trackStatus.ts
+ * Unknown codes default to PENDING.
+ */
+export declare function mapFoxpostStatusToCanonical(foxpostStatus: string): "PENDING" | "IN_TRANSIT" | "OUT_FOR_DELIVERY" | "DELIVERED" | "EXCEPTION" | "RETURNED" | "CANCELLED";
+/**
+ * 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 declare function mapFoxpostTrackToCanonical(track: FoxpostTrackDTO): TrackingEvent;
+/**
+ * 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 declare function mapFoxpostTraceToCanonical(trace: FoxpostTraceDTO | {
+    statusDate: string | Date;
+    status?: string;
+    shortName?: string;
+    longName?: string;
+}): TrackingEvent;
+/**
+ * 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 declare function mapParcelToFoxpostCarrierType(parcel: Parcel, options?: {
+    cod?: number;
+    comment?: string;
+    deliveryNote?: string;
+    fragile?: boolean;
+}): FoxpostParcel;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mappers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EACV,mBAAmB,IAAI,oBAAoB,EAC3C,QAAQ,IAAI,eAAe,EAC3B,QAAQ,IAAI,eAAe,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAsB,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAGtG,QAAA,MAAM,aAAa,sCAAuC,CAAC;AAC3D,KAAK,WAAW,GAAG,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;AAEhD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAC9J,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAUA;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAwB5E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,GACL,0BAA0B,CAuD5B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,GACL,oBAAoB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CA8CjD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,GACpB,SAAS,GAAG,YAAY,GAAG,kBAAkB,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAGtG;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,GACrB,aAAa,CAQf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7G,aAAa,CAuBf;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,aAAa,CAoDf"}