@shopickup/adapters-foxpost 0.0.1

package/dist/capabilities/parcels.js

@@ -0,0 +1,233 @@
+/**
+ * Foxpost Adapter: Parcel Creation Capabilities
+ * Handles CREATE_PARCEL and CREATE_PARCELS operations
+ */
+import { CarrierError, serializeForLog, errorToLog } from "@shopickup/core";
+import { mapParcelToFoxpostRequest, } from '../mappers/index.js';
+import { translateFoxpostError, sanitizeResponseForLog } from '../errors.js';
+import { safeValidateCreateParcelRequest, safeValidateCreateParcelsRequest, safeValidateFoxpostCreateResponse } from '../validation.js';
+import { buildFoxpostHeaders } from '../utils/httpUtils.js';
+/**
+ * Create a single parcel in Foxpost
+ * Delegates to createParcels to reuse batching logic
+ */
+export async function createParcel(req, ctx, createParcelsImpl) {
+    // Validate request format and credentials
+    const validated = safeValidateCreateParcelRequest(req);
+    if (!validated.success) {
+        throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: serializeForLog(validated.error) });
+    }
+    const batchReq = {
+        parcels: [req.parcel],
+        credentials: req.credentials,
+        options: req.options,
+    };
+    const response = await createParcelsImpl(batchReq, ctx);
+    // Expect CreateParcelsResponse. Validate shape and return the first result.
+    if (!response || !Array.isArray(response.results)) {
+        // Defensive: unexpected shape from createParcels
+        throw new CarrierError("Unexpected response shape from createParcels", "Transient", { raw: serializeForLog(response) });
+    }
+    const results = response.results;
+    if (results.length === 0) {
+        throw new CarrierError("createParcels returned an empty results array", "Transient", { raw: serializeForLog(response) });
+    }
+    // Return the first parcel result, but attach rawCarrierResponse for batch-level context
+    const result = results[0];
+    return {
+        ...result,
+        rawCarrierResponse: response.rawCarrierResponse,
+    };
+}
+/**
+ * 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.
+ *
+ * @returns CreateParcelsResponse with summary and per-item results
+ */
+export async function createParcels(req, ctx, resolveBaseUrl) {
+    try {
+        // Validate request format and credentials
+        const validated = safeValidateCreateParcelsRequest(req);
+        if (!validated.success) {
+            throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: validated.error });
+        }
+        if (!ctx.http) {
+            throw new CarrierError("HTTP client not provided in context", "Permanent");
+        }
+        if (!Array.isArray(req.parcels) || req.parcels.length === 0) {
+            return {
+                results: [],
+                successCount: 0,
+                failureCount: 0,
+                totalCount: 0,
+                allSucceeded: false,
+                allFailed: false,
+                someFailed: false,
+                summary: "No parcels to process",
+            };
+        }
+        // For simplicity require uniform test-mode and credentials across the batch
+        const baseUrl = resolveBaseUrl(validated.data.options);
+        const useTestApi = validated.data.options?.useTestApi ?? false;
+        const isWeb = !useTestApi;
+        // Validate and map each canonical parcel to Foxpost request format
+        // mapParcelToFoxpostRequest returns strongly-typed FoxCreateParcelRequestItem
+        const foxpostRequestsWithValidation = req.parcels.map((parcel, idx) => {
+            // Map canonical parcel to Foxpost CreateParcelRequest format
+            const foxpostRequest = mapParcelToFoxpostRequest(parcel);
+            // Validate the mapped request shape before sending to Foxpost API
+            try {
+                // Ensure required fields are present for the delivery type
+                if (!foxpostRequest.recipientName || !foxpostRequest.recipientEmail || !foxpostRequest.recipientPhone) {
+                    throw new Error('Missing required recipient fields (name, email, phone)');
+                }
+                // For HOME delivery, validate address fields are all present
+                if (foxpostRequest.recipientCity || foxpostRequest.recipientZip || foxpostRequest.recipientAddress) {
+                    if (!(foxpostRequest.recipientCity && foxpostRequest.recipientZip && foxpostRequest.recipientAddress)) {
+                        throw new Error('Address fields must be either all present (HD) or all absent (APM)');
+                    }
+                }
+                // For APM delivery, validate destination is present
+                if (!foxpostRequest.recipientCity && !foxpostRequest.recipientZip && !foxpostRequest.recipientAddress) {
+                    if (!foxpostRequest.destination) {
+                        throw new Error('APM parcel must have destination field set');
+                    }
+                }
+            }
+            catch (validationErr) {
+                throw new CarrierError(`Invalid carrier payload for parcel ${idx}: ${validationErr.message}`, "Validation", { raw: serializeForLog({ parcelIdx: idx, parcelId: parcel.id }) });
+            }
+            return foxpostRequest;
+        });
+        ctx.logger?.debug("Foxpost: Creating parcels batch", {
+            count: req.parcels.length,
+            testMode: useTestApi,
+        });
+        const httpResponse = await ctx.http.post(`${baseUrl}/api/parcel?isWeb=${isWeb}&isRedirect=false`, foxpostRequestsWithValidation, {
+            headers: buildFoxpostHeaders(validated.data.credentials),
+        });
+        // Extract body from normalized HttpResponse and validate shape
+        const carrierRespBody = httpResponse.body;
+        // Validate the response shape
+        const responseValidation = safeValidateFoxpostCreateResponse(carrierRespBody);
+        if (!responseValidation.success) {
+            ctx.logger?.warn("Foxpost: Response validation failed", {
+                errors: serializeForLog(responseValidation.error.issues)
+            });
+            // Continue anyway - be lenient with response shape
+        }
+        if (!carrierRespBody || !Array.isArray(carrierRespBody.parcels)) {
+            throw new CarrierError("Invalid response from Foxpost", "Transient", { raw: serializeForLog(sanitizeResponseForLog(httpResponse)) });
+        }
+        const response = carrierRespBody;
+        // Check if response indicates an overall validation failure
+        if (response.valid === false && response.errors && Array.isArray(response.errors)) {
+            const firstError = response.errors[0];
+            const errorCode = firstError?.message || "VALIDATION_ERROR";
+            const errorField = firstError?.field || "unknown";
+            throw new CarrierError(`Validation error: ${errorCode} (field: ${errorField})`, "Validation", {
+                carrierCode: errorCode,
+                raw: serializeForLog(response)
+            });
+        }
+        // Map carrier response array -> CarrierResource[]
+        const results = (response.parcels || []).map((p, idx) => {
+            // Check for parcel-level validation errors
+            if (p.errors && Array.isArray(p.errors) && p.errors.length > 0) {
+                const errors = p.errors.map((err) => ({
+                    field: err.field,
+                    code: err.message, // Foxpost returns error code in 'message' field
+                    message: `${err.field ? `Field '${err.field}': ` : ''}${err.message}`,
+                }));
+                ctx.logger?.warn("Foxpost: Parcel validation errors", {
+                    parcelIdx: idx,
+                    errorCount: errors.length,
+                    errorSummary: errors.map(e => `${e.field || 'unknown'}: ${e.code}`),
+                    refCode: p.refCode,
+                    errors: serializeForLog(errors),
+                });
+                const rawParcel = serializeForLog(p);
+                rawParcel.errors = errors;
+                const failedResource = {
+                    carrierId: undefined,
+                    status: "failed",
+                    raw: rawParcel,
+                    errors,
+                };
+                return failedResource;
+            }
+            // Check for successful barcode assignment (try multiple field names)
+            const carrierId = p.clFoxId || p.barcode || p.newBarcode;
+            if (!carrierId) {
+                ctx.logger?.warn("Foxpost: Parcel created returned no barcode", {
+                    parcelIdx: idx,
+                    refCode: p.refCode,
+                    availableFields: Object.keys(p).join(', '),
+                });
+                const failedResource = {
+                    carrierId: undefined,
+                    status: "failed",
+                    raw: serializeForLog(p),
+                    errors: [{
+                            field: "clFoxId/barcode",
+                            message: "No barcode assigned by carrier",
+                            code: "NO_BARCODE_ASSIGNED",
+                        }],
+                };
+                return failedResource;
+            }
+            // Success - parcel was created with barcode
+            return {
+                carrierId,
+                status: "created",
+                raw: serializeForLog(p),
+            };
+        });
+        // Calculate summary statistics
+        const successCount = results.filter(r => r.status === 'created').length;
+        const failureCount = results.filter(r => r.status === 'failed').length;
+        const totalCount = results.length;
+        // Determine summary text
+        let summary;
+        if (failureCount === 0) {
+            summary = `All ${totalCount} parcels created successfully`;
+        }
+        else if (successCount === 0) {
+            summary = `All ${totalCount} parcels failed`;
+        }
+        else {
+            summary = `Mixed results: ${successCount} succeeded, ${failureCount} failed`;
+        }
+        ctx.logger?.info("Foxpost: Parcels creation finished", {
+            count: results.length,
+            testMode: useTestApi,
+            summary,
+            successCount,
+            failureCount,
+        });
+        // Return strongly-typed response with full carrier response for debugging
+        return {
+            results,
+            successCount,
+            failureCount,
+            totalCount,
+            allSucceeded: failureCount === 0 && totalCount > 0,
+            allFailed: successCount === 0 && totalCount > 0,
+            someFailed: successCount > 0 && failureCount > 0,
+            summary,
+            rawCarrierResponse: serializeForLog(sanitizeResponseForLog(httpResponse)),
+        };
+    }
+    catch (error) {
+        ctx.logger?.error("Foxpost: Error creating parcels batch", {
+            error: errorToLog(error),
+        });
+        if (error instanceof CarrierError) {
+            throw error;
+        }
+        throw translateFoxpostError(error);
+    }
+}

package/dist/capabilities/pickup-points.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Foxpost Pickup Points Capability
+ *
+ * Fetches and normalizes the list of Foxpost APMs (Automated Parcel Machines) and pickup points
+ * from the public JSON feed at https://cdn.foxpost.hu/foxplus.json
+ *
+ * The feed is updated hourly by Foxpost and contains all active pickup points with their
+ * details, opening hours, payment options, and services.
+ */
+import type { FetchPickupPointsRequest, FetchPickupPointsResponse, AdapterContext } from "@shopickup/core";
+/**
+ * Fetch pickup points (APMs) from Foxpost
+ *
+ * Fetches the public JSON feed from https://cdn.foxpost.hu/foxplus.json
+ * and normalizes each APM entry to the canonical PickupPoint format.
+ *
+ * Note on logging: By default, raw APM responses are logged as summaries only
+ * to avoid polluting logs with hundreds of pickup point entries.
+ * To customize logging behavior, pass loggingOptions in the adapter context:
+ * {
+ *   loggingOptions: {
+ *     logRawResponse: true,        // Log full response
+ *     logRawResponse: false,       // Skip logging raw entirely
+ *     logRawResponse: 'summary',   // Log only summary (default)
+ *     maxArrayItems: 50,           // Increase items shown in arrays
+ *     silentOperations: ['fetchPickupPoints']  // Suppress all logging
+ *   }
+ * }
+ *
+ * When using the withOperationName wrapper from @shopickup/core, the operation name
+ * is automatically injected and logging control is applied automatically.
+ *
+ * @param req Request with optional filters and credentials (not used for public feed)
+ * @param ctx Adapter context with HTTP client (operationName set by wrapper or manually)
+ * @returns FetchPickupPointsResponse with normalized pickup points
+ */
+export declare function fetchPickupPoints(req: FetchPickupPointsRequest, ctx: AdapterContext): Promise<FetchPickupPointsResponse>;
+//# sourceMappingURL=pickup-points.d.ts.map

package/dist/capabilities/pickup-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickup-points.d.ts","sourceRoot":"","sources":["../../src/capabilities/pickup-points.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAEzB,cAAc,EAEf,MAAM,iBAAiB,CAAC;AA4GzB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,yBAAyB,CAAC,CA8IpC"}

package/dist/capabilities/pickup-points.js

@@ -0,0 +1,225 @@
+/**
+ * Foxpost Pickup Points Capability
+ *
+ * Fetches and normalizes the list of Foxpost APMs (Automated Parcel Machines) and pickup points
+ * from the public JSON feed at https://cdn.foxpost.hu/foxplus.json
+ *
+ * The feed is updated hourly by Foxpost and contains all active pickup points with their
+ * details, opening hours, payment options, and services.
+ */
+import { CarrierError, safeLog, createLogEntry } from "@shopickup/core";
+import { safeValidateFetchPickupPointsRequest, safeValidateFoxpostApmEntry, } from "../validation.js";
+/**
+ * Normalize a Foxpost APM entry to canonical PickupPoint
+ */
+function mapFoxpostApmToPickupPoint(apm) {
+    // Determine primary ID: operator_id if present and non-empty, otherwise place_id
+    const operatorId = apm.operator_id?.trim();
+    const placeId = apm.place_id?.toString().trim();
+    const id = operatorId || placeId || `fallback-${Math.random().toString(36).slice(2, 9)}`;
+    const providerId = operatorId ? placeId : operatorId;
+    // Parse coordinates (Zod already coerced them to numbers in validation)
+    let latitude = apm.geolat;
+    let longitude = apm.geolng;
+    // Determine allowed services from allowed2 field
+    // "ALL" = both pickup and dropoff
+    // "B2C" = typically both pickup and dropoff for B2C
+    // "C2C" = consumer-to-consumer (no dropoff)
+    let pickupAllowed = true; // default to true as most APMs support pickup
+    let dropoffAllowed = true; // default to true as most APMs support dropoff
+    if (apm.allowed2 === "C2C") {
+        // C2C typically means dropoff only (no pickup)
+        dropoffAllowed = true;
+        pickupAllowed = false;
+    }
+    else if (apm.allowed2 === "B2C") {
+        // B2C allows both
+        dropoffAllowed = true;
+        pickupAllowed = true;
+    }
+    else if (apm.allowed2 === "ALL") {
+        // ALL allows both
+        dropoffAllowed = true;
+        pickupAllowed = true;
+    }
+    // Build payment options array
+    const paymentOptions = [];
+    if (apm.cardPayment) {
+        paymentOptions.push("card");
+    }
+    if (apm.cashPayment) {
+        paymentOptions.push("cash");
+    }
+    // Include unified paymentOptions if available
+    if (apm.paymentOptions && Array.isArray(apm.paymentOptions)) {
+        paymentOptions.push(...apm.paymentOptions.filter((p) => !paymentOptions.includes(p)));
+    }
+    // Build address string if not provided
+    let address = apm.address;
+    if (!address && (apm.street || apm.city || apm.zip)) {
+        const parts = [];
+        if (apm.zip)
+            parts.push(apm.zip);
+        if (apm.city)
+            parts.push(apm.city);
+        if (apm.street)
+            parts.push(apm.street);
+        address = parts.join(", ");
+    }
+    // Collect all carrier-specific fields in metadata
+    const metadata = {
+        depot: apm.depot,
+        load: apm.load,
+        apmType: apm.apmType,
+        substitutes: apm.substitutes,
+        variant: apm.variant,
+        fillEmptyList: apm.fillEmptyList,
+        ssapt: apm.ssapt,
+        sdapt: apm.sdapt,
+    };
+    // Remove undefined keys from metadata
+    const cleanedMetadata = Object.fromEntries(Object.entries(metadata).filter(([, value]) => value !== undefined));
+    return {
+        id,
+        providerId: providerId || undefined,
+        name: apm.name,
+        country: apm.country?.toLowerCase(),
+        postalCode: apm.zip,
+        city: apm.city,
+        street: apm.street,
+        address,
+        findme: apm.findme,
+        latitude,
+        longitude,
+        openingHours: apm.open,
+        dropoffAllowed,
+        pickupAllowed,
+        isOutdoor: apm.isOutdoor,
+        paymentOptions: paymentOptions.length > 0 ? paymentOptions : undefined,
+        contact: undefined, // Foxpost doesn't provide contact info in feed
+        metadata: Object.keys(cleanedMetadata).length > 0 ? cleanedMetadata : undefined,
+        raw: apm,
+    };
+}
+/**
+ * Fetch pickup points (APMs) from Foxpost
+ *
+ * Fetches the public JSON feed from https://cdn.foxpost.hu/foxplus.json
+ * and normalizes each APM entry to the canonical PickupPoint format.
+ *
+ * Note on logging: By default, raw APM responses are logged as summaries only
+ * to avoid polluting logs with hundreds of pickup point entries.
+ * To customize logging behavior, pass loggingOptions in the adapter context:
+ * {
+ *   loggingOptions: {
+ *     logRawResponse: true,        // Log full response
+ *     logRawResponse: false,       // Skip logging raw entirely
+ *     logRawResponse: 'summary',   // Log only summary (default)
+ *     maxArrayItems: 50,           // Increase items shown in arrays
+ *     silentOperations: ['fetchPickupPoints']  // Suppress all logging
+ *   }
+ * }
+ *
+ * When using the withOperationName wrapper from @shopickup/core, the operation name
+ * is automatically injected and logging control is applied automatically.
+ *
+ * @param req Request with optional filters and credentials (not used for public feed)
+ * @param ctx Adapter context with HTTP client (operationName set by wrapper or manually)
+ * @returns FetchPickupPointsResponse with normalized pickup points
+ */
+export async function fetchPickupPoints(req, ctx) {
+    if (!ctx.http) {
+        throw new CarrierError("HTTP client not provided in adapter context", "Permanent", { raw: "Missing ctx.http" });
+    }
+    const feedUrl = "https://cdn.foxpost.hu/foxplus.json";
+    try {
+        const validatedReq = safeValidateFetchPickupPointsRequest(req);
+        if (!validatedReq.success) {
+            throw new CarrierError(`Invalid request: ${validatedReq.error.message}`, "Validation", { raw: validatedReq.error.issues });
+        }
+        // Normalize namespaced options into a flat internal shape for adapter logic.
+        const internalOptions = {
+            country: validatedReq.data.options?.foxpost?.country,
+            bbox: validatedReq.data.options?.foxpost?.bbox,
+        };
+        // Fetch the public JSON feed (no authentication needed)
+        // operationName is already set by withOperationName wrapper
+        safeLog(ctx.logger, 'debug', 'Fetching Foxpost APM feed', { url: feedUrl }, ctx);
+        const response = await ctx.http.get(feedUrl);
+        // Extract body from normalized HttpResponse
+        const apmData = response.body;
+        // Validate response is an array
+        if (!Array.isArray(apmData)) {
+            throw new Error("Expected array of APMs from Foxpost feed, got: " + typeof apmData);
+        }
+        safeLog(ctx.logger, 'debug', 'Fetched Foxpost APM feed', createLogEntry({ url: feedUrl }, apmData, ctx), ctx);
+        // Map each entry to PickupPoint with per-entry validation
+        let points = apmData.map((entry) => {
+            try {
+                // Validate and coerce entry using Zod schema
+                const validation = safeValidateFoxpostApmEntry(entry);
+                if (!validation.success) {
+                    ctx.logger?.warn("Skipping invalid APM entry", {
+                        errors: validation.error.issues,
+                        entry: entry instanceof Object ? JSON.stringify(entry).substring(0, 100) : entry
+                    });
+                    return null;
+                }
+                // Map validated entry to PickupPoint
+                return mapFoxpostApmToPickupPoint(validation.data);
+            }
+            catch (err) {
+                ctx.logger?.warn("Failed to map APM entry", { error: String(err), entry: entry instanceof Object ? JSON.stringify(entry).substring(0, 100) : entry });
+                // Skip entries that can't be mapped
+                return null;
+            }
+        }).filter((p) => p !== null);
+        if (internalOptions.country) {
+            const countryFilter = internalOptions.country.toLowerCase();
+            points = points.filter((p) => p.country?.toLowerCase() === countryFilter);
+        }
+        if (internalOptions.bbox) {
+            const { north, south, east, west } = internalOptions.bbox;
+            points = points.filter((p) => {
+                if (p.latitude === undefined || p.longitude === undefined) {
+                    return false;
+                }
+                return (p.latitude <= north &&
+                    p.latitude >= south &&
+                    p.longitude <= east &&
+                    p.longitude >= west);
+            });
+        }
+        safeLog(ctx.logger, 'info', 'Successfully fetched and mapped Foxpost APMs', {
+            total: apmData.length,
+            succeeded: points.length,
+            failed: apmData.length - points.length,
+            appliedFilters: {
+                country: internalOptions.country,
+                bbox: internalOptions.bbox ? true : false,
+            },
+        }, ctx);
+        return {
+            points,
+            summary: {
+                totalCount: points.length,
+                updatedAt: new Date().toISOString(),
+            },
+            rawCarrierResponse: apmData,
+        };
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        ctx.logger?.error("Failed to fetch Foxpost APM feed", { error: errorMessage, url: feedUrl });
+        // Categorize error for retry logic
+        let category = "Transient";
+        let details = { raw: err };
+        // If it's a network error or 5xx, it's transient
+        // If it's 4xx or parsing error, it's permanent
+        if (err instanceof Error && err.message.includes("Expected array")) {
+            category = "Permanent";
+            details.reason = "Invalid response format";
+        }
+        throw new CarrierError(`Failed to fetch Foxpost APM feed: ${errorMessage}`, category, details);
+    }
+}

package/dist/capabilities/track.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Foxpost Adapter: Parcel Tracking Capability
+ * Handles TRACK operation
+ */
+import type { AdapterContext, TrackingRequest, TrackingUpdate } from "@shopickup/core";
+import type { ResolveBaseUrl } from '../utils/resolveBaseUrl.js';
+/**
+ * Track a parcel by its clFoxId or uniqueBarcode using the 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 } }
+ */
+export declare function track(req: TrackingRequest, ctx: AdapterContext, resolveBaseUrl: ResolveBaseUrl): Promise<TrackingUpdate>;
+//# sourceMappingURL=track.d.ts.map

package/dist/capabilities/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/capabilities/track.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,cAAc,EACf,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAsB,KAAK,CACzB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,cAAc,CAAC,CAoHzB"}

package/dist/capabilities/track.js

@@ -0,0 +1,99 @@
+/**
+ * Foxpost Adapter: Parcel Tracking Capability
+ * Handles TRACK operation
+ */
+import { CarrierError, serializeForLog, errorToLog } from "@shopickup/core";
+import { mapFoxpostTraceToCanonical, } from '../mappers/index.js';
+import { translateFoxpostError } from '../errors.js';
+import { safeValidateTrackingRequest, safeValidateFoxpostTracking } from '../validation.js';
+import { buildFoxpostHeaders } from '../utils/httpUtils.js';
+/**
+ * Track a parcel by its clFoxId or uniqueBarcode using the 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 } }
+ */
+export async function track(req, ctx, resolveBaseUrl) {
+    try {
+        // Validate request format and credentials
+        const validated = safeValidateTrackingRequest(req);
+        if (!validated.success) {
+            throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: serializeForLog(validated.error) });
+        }
+        if (!ctx.http) {
+            throw new CarrierError("HTTP client not provided in context", "Permanent");
+        }
+        // Extract useTestApi from validated request (per-call test mode selection)
+        const useTestApi = validated.data.options?.useTestApi ?? false;
+        const baseUrl = resolveBaseUrl(validated.data.options);
+        // Extract strongly-typed credentials from validated request
+        const trackingNumber = validated.data.trackingNumber;
+        ctx.logger?.debug("Foxpost: Tracking parcel", {
+            trackingNumber,
+            testMode: useTestApi,
+        });
+        // Get tracking history via /api/tracking/{barcode} endpoint with proper typing
+        const url = `${baseUrl}/api/tracking/${trackingNumber}`;
+        const httpResponse = await ctx.http.get(url, {
+            headers: buildFoxpostHeaders(validated.data.credentials),
+        });
+        // Extract body from normalized HttpResponse
+        const response = httpResponse.body;
+        // Foxpost returns an empty body for missing tracking numbers on some environments.
+        // Treat that as a not-found / validation-style miss instead of trying to validate it.
+        if (response == null || (typeof response === 'string' && response.trim() === '')) {
+            throw new CarrierError(`No tracking information found for ${trackingNumber}`, 'NotFound', { raw: serializeForLog({ status: httpResponse.status, body: response }) });
+        }
+        // Validate response against Zod schema
+        const responseValidation = safeValidateFoxpostTracking(response);
+        if (!responseValidation.success) {
+            throw new CarrierError(`Invalid tracking response: ${responseValidation.error.message}`, "Validation", { raw: serializeForLog(responseValidation.error) });
+        }
+        const validatedResponse = responseValidation.data;
+        // Validate clFox is present
+        if (!validatedResponse.clFox) {
+            throw new CarrierError(`No tracking information found for ${trackingNumber}`, "NotFound");
+        }
+        // Validate traces array exists
+        if (!Array.isArray(validatedResponse.traces)) {
+            throw new CarrierError(`Invalid tracking response: traces array missing for ${trackingNumber}`, "Transient", { raw: serializeForLog(validatedResponse) });
+        }
+        // Convert Foxpost traces to canonical TrackingEvents
+        // Traces arrive in reverse chronological order (latest first), but we want them chronological for the response
+        const events = validatedResponse.traces
+            .map(mapFoxpostTraceToCanonical)
+            .reverse(); // Reverse to get chronological order
+        // Current status is from the latest trace (which is first in the API response)
+        const currentStatus = validatedResponse.traces.length > 0
+            ? mapFoxpostTraceToCanonical(validatedResponse.traces[0]).status
+            : "PENDING";
+        ctx.logger?.info("Foxpost: Tracking retrieved", {
+            trackingNumber,
+            clFox: validatedResponse.clFox,
+            status: currentStatus,
+            events: events.length,
+            parcelType: validatedResponse.parcelType,
+            sendType: validatedResponse.sendType,
+            testMode: useTestApi,
+        });
+        return {
+            trackingNumber,
+            events,
+            status: currentStatus,
+            lastUpdate: events.length > 0 ? events[events.length - 1].timestamp : null,
+            rawCarrierResponse: validatedResponse,
+        };
+    }
+    catch (error) {
+        if (error instanceof CarrierError) {
+            throw error;
+        }
+        ctx.logger?.error("Foxpost: Error tracking parcel", {
+            trackingNumber: req.trackingNumber,
+            error: errorToLog(error),
+        });
+        throw translateFoxpostError(error);
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Foxpost HTTP Client Utilities
+ * Thin utilities for building Foxpost API requests
+ */
+import type { FoxpostCredentials } from '../validation.js';
+/**
+ * Build standard Foxpost auth headers
+ * Requires both Basic auth (username:password) and API key
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export declare function buildFoxpostHeaders(credentials: FoxpostCredentials): Record<string, string>;
+/**
+ * Build Foxpost headers for binary responses (e.g., PDF)
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export declare function buildFoxpostBinaryHeaders(credentials: FoxpostCredentials): Record<string, string>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3F;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASjG"}

package/dist/client/index.js

@@ -0,0 +1,30 @@
+/**
+ * Foxpost HTTP Client Utilities
+ * Thin utilities for building Foxpost API requests
+ */
+/**
+ * Build standard Foxpost auth headers
+ * Requires both Basic auth (username:password) and API key
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export function buildFoxpostHeaders(credentials) {
+    const { apiKey, basicUsername, basicPassword } = credentials;
+    const basicAuth = Buffer.from(`${basicUsername}:${basicPassword}`).toString("base64");
+    return {
+        "Content-Type": "application/json",
+        "Authorization": `Basic ${basicAuth}`,
+        ...(apiKey && { "Api-key": apiKey }),
+    };
+}
+/**
+ * Build Foxpost headers for binary responses (e.g., PDF)
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export function buildFoxpostBinaryHeaders(credentials) {
+    const { apiKey, basicUsername, basicPassword } = credentials;
+    const basicAuth = Buffer.from(`${basicUsername}:${basicPassword}`).toString("base64");
+    return {
+        "Authorization": `Basic ${basicAuth}`,
+        ...(apiKey && { "Api-key": apiKey }),
+    };
+}