@shopickup/adapters-mpl 0.0.1

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

@@ -0,0 +1,41 @@
+/**
+ * MPL Pickup Points Capability
+ *
+ * Fetches and normalizes the list of delivery places and pickup points
+ * from the MPL API endpoint `/deliveryplace`.
+ *
+ * Supports filtering by postCode, city, or servicePointType.
+ * Returns normalized PickupPoint entries in canonical format.
+ */
+import type { FetchPickupPointsRequest, FetchPickupPointsResponse, AdapterContext } from "@shopickup/core";
+import type { ResolveBaseUrl } from "../utils/resolveBaseUrl.js";
+/**
+ * Fetch pickup points from MPL API
+ *
+ * Makes an authenticated request to the `/deliveryplace` endpoint with optional filters.
+ *
+ * Handles both success and error responses:
+ * - 200 OK: Returns normalized PickupPoint array
+ * - 4xx/5xx: Translates to CarrierError with appropriate retry category
+ *
+ * Note on logging: By default, raw 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: []         // Enable logging for this operation
+ *   }
+ * }
+ *
+ * @param req Request containing credentials and optional filters (postCode, city, servicePointType)
+ * @param ctx Adapter context with HTTP client and logger
+ * @param resolveBaseUrl Function to resolve API base URL (test vs. production)
+ * @returns FetchPickupPointsResponse with normalized pickup points
+ * @throws CarrierError on HTTP error or response parsing failure
+ */
+export declare function fetchPickupPoints(req: FetchPickupPointsRequest, ctx: AdapterContext, resolveBaseUrl: ResolveBaseUrl): 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,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAwJjE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,yBAAyB,CAAC,CAgOpC"}

package/dist/capabilities/pickup-points.js

@@ -0,0 +1,294 @@
+/**
+ * MPL Pickup Points Capability
+ *
+ * Fetches and normalizes the list of delivery places and pickup points
+ * from the MPL API endpoint `/deliveryplace`.
+ *
+ * Supports filtering by postCode, city, or servicePointType.
+ * Returns normalized PickupPoint entries in canonical format.
+ */
+import { CarrierError, safeLog, createLogEntry, serializeForLog } from "@shopickup/core";
+import { safeValidateFetchPickupPointsRequest, isGatewayError, isSuccessResponse, } from "../validation.js";
+import { buildMPLHeaders } from "../utils/httpUtils.js";
+/**
+ * Maps an MPL delivery place entry to canonical PickupPoint
+ *
+ * Handles:
+ * - Coordinate parsing from geocodeLat/geocodeLong (may be numbers)
+ * - Address construction from address field
+ * - Service point type validation
+ * - Metadata preservation for carrier-specific fields
+ */
+function mapMplDeliveryPlaceToPickupPoint(entry) {
+    const qr = entry.deliveryplacesQueryResult;
+    // Use the delivery place ID as primary identifier
+    const id = qr.id || `mpl-${Math.random().toString(36).slice(2, 9)}`;
+    // Parse coordinates - geocodeLat and geocodeLong are numbers
+    let latitude;
+    let longitude;
+    if (qr.geocodeLat !== undefined && qr.geocodeLat !== null) {
+        latitude = typeof qr.geocodeLat === 'string' ? parseFloat(qr.geocodeLat) : qr.geocodeLat;
+        latitude = isNaN(latitude) ? undefined : latitude;
+    }
+    if (qr.geocodeLong !== undefined && qr.geocodeLong !== null) {
+        longitude = typeof qr.geocodeLong === 'string' ? parseFloat(qr.geocodeLong) : qr.geocodeLong;
+        longitude = isNaN(longitude) ? undefined : longitude;
+    }
+    // Determine allowed services based on servicePointType
+    // For MPL, servicePointType indicates what types of operations are allowed at this point
+    // These are the pickup-capable service point types available in the request filter
+    let pickupAllowed = true; // Most delivery places support pickup
+    let dropoffAllowed = true; // Most delivery places support dropoff
+    const types = entry.servicePointType || [];
+    // ServicePointType options include:
+    // 'PM' - Postán Maradó (Post Office) - typically both
+    // 'PP' - PostaPont (Post Point) - typically both
+    // 'CS' - Csomagautomata (Parcel Locker) - typically both pickup and dropoff
+    // Note: 'HA' and 'RA' are not in the pickup filter list but may appear in responses
+    // If no pickup-enabled service types are present, restrict to dropoff only
+    const pickupEnabledTypes = types.filter(t => t === 'PM' || t === 'PP' || t === 'CS');
+    if (types.length > 0 && pickupEnabledTypes.length === 0) {
+        pickupAllowed = false;
+    }
+    // Collect carrier-specific metadata
+    const metadata = {
+        deliveryplace: qr.deliveryplace,
+        errors: qr.errors && qr.errors.length > 0 ? qr.errors : null,
+    };
+    // Clean metadata - remove undefined keys
+    const cleanedMetadata = Object.fromEntries(Object.entries(metadata).filter(([, value]) => value !== undefined));
+    return {
+        id,
+        name: qr.deliveryplace,
+        country: 'hu', // MPL is Hungary-based
+        postalCode: qr.postCode,
+        city: qr.city,
+        address: qr.address,
+        latitude,
+        longitude,
+        dropoffAllowed,
+        pickupAllowed,
+        metadata: Object.keys(cleanedMetadata).length > 0 ? cleanedMetadata : undefined,
+        raw: entry,
+    };
+}
+/**
+ * Translates an MPL gateway error to a CarrierError with appropriate category and details
+ *
+ * Categorizes errors based on HTTP status and error details:
+ * - 400/404: Validation errors (Permanent - don't retry)
+ * - 401/403: Auth errors (Auth - don't retry, check credentials)
+ * - 429: Rate limit (RateLimit - retry with backoff)
+ * - 500/503: Server errors (Transient - retry)
+ */
+function translateMplError(error, httpStatus, headers) {
+    const faultString = error.fault?.faultstring || 'Unknown error';
+    const errorCode = error.fault?.detail?.errorcode || 'UNKNOWN';
+    let category;
+    const details = {
+        mplErrorCode: errorCode,
+        mplFaultString: faultString,
+        raw: error,
+    };
+    if (httpStatus === 400 || httpStatus === 404) {
+        category = httpStatus === 404 ? 'NotFound' : 'Validation';
+    }
+    else if (httpStatus === 401) {
+        category = 'Auth';
+    }
+    else if (httpStatus === 403) {
+        category = 'Auth';
+    }
+    else if (httpStatus === 429) {
+        category = 'RateLimit';
+        // Extract quota information from headers
+        const retryAfter = headers['retry-after'];
+        if (retryAfter) {
+            const retryAfterMs = parseInt(String(retryAfter)) * 1000;
+            details.retryAfterMs = retryAfterMs;
+        }
+        // Include quota headers if available
+        if (headers['x-quota-reset'])
+            details.quotaReset = headers['x-quota-reset'];
+        if (headers['x-quota-allowed'])
+            details.quotaAllowed = headers['x-quota-allowed'];
+        if (headers['x-quota-available'])
+            details.quotaAvailable = headers['x-quota-available'];
+    }
+    else if (httpStatus >= 500) {
+        category = 'Transient';
+    }
+    else {
+        category = 'Transient'; // Default to transient for unknown statuses
+    }
+    return new CarrierError(`MPL API error: ${faultString} (${errorCode})`, category, details);
+}
+/**
+ * Fetch pickup points from MPL API
+ *
+ * Makes an authenticated request to the `/deliveryplace` endpoint with optional filters.
+ *
+ * Handles both success and error responses:
+ * - 200 OK: Returns normalized PickupPoint array
+ * - 4xx/5xx: Translates to CarrierError with appropriate retry category
+ *
+ * Note on logging: By default, raw 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: []         // Enable logging for this operation
+ *   }
+ * }
+ *
+ * @param req Request containing credentials and optional filters (postCode, city, servicePointType)
+ * @param ctx Adapter context with HTTP client and logger
+ * @param resolveBaseUrl Function to resolve API base URL (test vs. production)
+ * @returns FetchPickupPointsResponse with normalized pickup points
+ * @throws CarrierError on HTTP error or response parsing failure
+ */
+export async function fetchPickupPoints(req, ctx, resolveBaseUrl) {
+    if (!ctx.http) {
+        throw new CarrierError("HTTP client not provided in adapter context", "Permanent", { raw: "Missing ctx.http" });
+    }
+    try {
+        // Validate request format and credentials
+        const validated = safeValidateFetchPickupPointsRequest(req);
+        if (!validated.success) {
+            throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: serializeForLog(validated.error) });
+        }
+        // Normalize namespaced options into a flat internal shape for adapter logic.
+        const internalOptions = {
+            useTestApi: validated.data.options.useTestApi ?? false,
+            accountingCode: validated.data.options.mpl.accountingCode,
+            postCode: validated.data.options.mpl.postCode || "",
+            city: validated.data.options.mpl.city || "",
+            servicePointType: validated.data.options.mpl.servicePointType || [],
+        };
+        const useTestApi = internalOptions.useTestApi;
+        const postCode = internalOptions.postCode;
+        const city = internalOptions.city;
+        const servicePointType = internalOptions.servicePointType;
+        const filters = { postCode, city, servicePointType };
+        const credentialType = validated.data.credentials.authType;
+        const baseUrl = resolveBaseUrl(validated.data.options);
+        // Log the fetch attempt
+        safeLog(ctx.logger, 'debug', 'Fetching MPL pickup points with filters', createLogEntry({ useTestApi, filters, credentialType, endpoint: '/deliveryplace' }, null, ctx, ['fetchPickupPoints']), ctx, ['fetchPickupPoints']);
+        // Make the API request
+        const httpResponse = await ctx.http.post(`${baseUrl}/deliveryplace`, {
+            deliveryPlacesQuery: {
+                postCode,
+                city,
+            },
+            servicePointType,
+        }, {
+            headers: buildMPLHeaders(validated.data.credentials, internalOptions.accountingCode),
+        });
+        // Handle non-200 responses (gateway errors)
+        if (httpResponse.status !== 200) {
+            const body = httpResponse.body;
+            if (isGatewayError(body)) {
+                const translatedError = translateMplError(body, httpResponse.status, httpResponse.headers);
+                ctx.logger?.warn("MPL API error response", {
+                    status: httpResponse.status,
+                    error: translatedError.message,
+                    category: translatedError.category,
+                });
+                throw translatedError;
+            }
+            else {
+                // Unexpected response format for error status
+                throw new CarrierError(`MPL API returned status ${httpResponse.status} with unexpected response format`, "Transient", { raw: body });
+            }
+        }
+        // Validate 200 response structure - strict array check
+        const body = httpResponse.body;
+        if (!isSuccessResponse(body)) {
+            throw new CarrierError("Invalid response format from MPL API: expected array of pickup points", "Permanent", { raw: body });
+        }
+        // Body is now guaranteed to be an array of MPLPickupPointEntry
+        const apmData = body;
+        if (apmData.length === 0) {
+            safeLog(ctx.logger, 'debug', 'MPL API returned empty pickup points array', createLogEntry({ count: 0, filters }, null, ctx, ['fetchPickupPoints']), ctx, ['fetchPickupPoints']);
+            return {
+                points: [],
+                summary: {
+                    totalCount: 0,
+                    updatedAt: new Date().toISOString(),
+                },
+                rawCarrierResponse: apmData,
+            };
+        }
+        safeLog(ctx.logger, 'debug', 'MPL API response received', createLogEntry({ count: apmData.length, filters }, apmData, ctx, ['fetchPickupPoints']), ctx, ['fetchPickupPoints']);
+        // Map each delivery place to canonical PickupPoint with per-entry validation
+        const points = apmData
+            .map((entry, index) => {
+            try {
+                // Validate entry structure - lenient approach like Foxpost
+                if (!entry || typeof entry !== 'object') {
+                    ctx.logger?.warn("Skipping invalid delivery place entry: not an object", {
+                        index,
+                        entryType: typeof entry,
+                    });
+                    return null;
+                }
+                const typedEntry = entry;
+                // Validate that required fields are present
+                if (!typedEntry.deliveryplacesQueryResult || !typedEntry.servicePointType) {
+                    ctx.logger?.warn("Skipping invalid delivery place entry: missing required fields", {
+                        index,
+                        hasQueryResult: !!typedEntry.deliveryplacesQueryResult,
+                        hasServicePointType: !!typedEntry.servicePointType,
+                    });
+                    return null;
+                }
+                return mapMplDeliveryPlaceToPickupPoint(typedEntry);
+            }
+            catch (err) {
+                ctx.logger?.warn("Failed to map delivery place entry", {
+                    index,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                // Skip entries that can't be mapped
+                return null;
+            }
+        })
+            .filter((p) => p !== null);
+        safeLog(ctx.logger, 'info', 'Successfully fetched and mapped MPL pickup points', {
+            count: points.length,
+            succeeded: points.length,
+            failed: apmData.length - points.length,
+            filters,
+        }, ctx, ['fetchPickupPoints']);
+        return {
+            points,
+            summary: {
+                totalCount: points.length,
+                updatedAt: new Date().toISOString(),
+            },
+            rawCarrierResponse: apmData,
+        };
+    }
+    catch (err) {
+        // Handle caught CarrierErrors
+        if (err instanceof CarrierError) {
+            throw err;
+        }
+        // Convert unknown errors to CarrierError
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        ctx.logger?.error("Failed to fetch MPL pickup points", {
+            error: errorMessage,
+            type: err instanceof Error ? err.constructor.name : typeof err,
+        });
+        // Determine error category based on error type
+        let category = 'Transient';
+        if (err instanceof Error && err.message.includes('Invalid response format')) {
+            category = 'Permanent';
+        }
+        throw new CarrierError(`Failed to fetch MPL pickup points: ${errorMessage}`, category, { raw: err });
+    }
+}

package/dist/capabilities/track.d.ts

@@ -0,0 +1,72 @@
+/**
+ * MPL Tracking Implementation
+ *
+ * Implements the TRACK capability using MPL's Pull-1 endpoints:
+ * - /v2/nyomkovetes/guest - Guest endpoint (public, no financial data)
+ * - /v2/nyomkovetes/registered - Registered endpoint (authenticated, includes financial data)
+ *
+ * Both endpoints return C-code tracking records that are normalized to canonical TrackingUpdate format.
+ */
+import type { AdapterContext, TrackingUpdate } from '@shopickup/core';
+import { type TrackingRequestMPL, type Pull500StartRequest, type Pull500StartResponse, type Pull500CheckRequest, type Pull500CheckResponse } from '../validation.js';
+import type { ResolveTrackingUrl } from '../utils/resolveBaseUrl.js';
+/**
+ * Submit batch tracking request using Pull-500 endpoint
+ *
+ * Submits up to 500 tracking numbers in a single request.
+ * Returns trackingGUID for polling results.
+ * Results are processed asynchronously by MPL (takes 1+ minutes).
+ *
+ * @param request - Pull-500 request with tracking numbers
+ * @param ctx - Adapter context with HTTP client
+ * @param resolveTrackingUrl - Function to resolve tracking API base URL
+ * @returns trackingGUID for use with trackPull500Check()
+ * @throws CarrierError for validation, auth, or network errors
+ */
+export declare function trackPull500Start(request: Pull500StartRequest, ctx: AdapterContext, resolveTrackingUrl: ResolveTrackingUrl): Promise<Pull500StartResponse>;
+/**
+ * Poll for Pull-500 batch tracking results
+ *
+ * Checks status of previously submitted batch request.
+ * Status progression: NEW -> INPROGRESS -> READY (or ERROR)
+ * When READY, response includes CSV report with tracking data.
+ *
+ * Recommendation: Wait 1+ minute before first poll, then poll every 30-60 seconds.
+ *
+ * @param request - Pull-500 check request with trackingGUID
+ * @param ctx - Adapter context with HTTP client
+ * @param resolveTrackingUrl - Function to resolve tracking API base URL
+ * @returns Pull-500 response with status and report (when ready)
+ * @throws CarrierError for validation, auth, or network errors
+ */
+export declare function trackPull500Check(request: Pull500CheckRequest, ctx: AdapterContext, resolveTrackingUrl: ResolveTrackingUrl): Promise<Pull500CheckResponse>;
+/**
+ * Track parcels using the registered endpoint (with financial data)
+ *
+ * Extends the core track() function to use /v2/nyomkovetes/registered
+ * instead of /v2/nyomkovetes/guest. Includes financial data:
+ * - Weight (C5)
+ * - Service Code (C2)
+ * - Dimensions (C41, C42, C43)
+ * - Declared value (C58)
+ *
+ * Requires authentication and is intended for power users / internal use.
+ *
+ * @param request - Tracking request with tracking numbers
+ * @param ctx - Adapter context with HTTP client
+ * @param resolveTrackingUrl - Function to resolve tracking API base URL
+ * @returns Array of TrackingUpdate objects with financial data included
+ * @throws CarrierError for validation, auth, or network errors
+ */
+export declare function trackRegistered(request: TrackingRequestMPL, ctx: AdapterContext, resolveTrackingUrl: ResolveTrackingUrl): Promise<TrackingUpdate[]>;
+/**
+ * Track one or more parcels using the Pull-1 endpoint
+ *
+ * @param request - Tracking request with tracking numbers and credentials
+ * @param ctx - Adapter context with HTTP client
+ * @param resolveTrackingUrl - Function to resolve tracking API base URL
+ * @returns Array of TrackingUpdate objects (one per tracking number)
+ * @throws CarrierError for various error scenarios
+ */
+export declare function track(request: TrackingRequestMPL, ctx: AdapterContext, resolveTrackingUrl: ResolveTrackingUrl): 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;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAOL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAK1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,EAAE,cAAc,EACnB,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,oBAAoB,CAAC,CAuF/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,EAAE,cAAc,EACnB,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,oBAAoB,CAAC,CAkE/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,cAAc,EACnB,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,cAAc,EAAE,CAAC,CAU3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,cAAc,EACnB,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,cAAc,EAAE,CAAC,CAmH3B"}