@shopickup/adapters-mpl 0.0.1

package/dist/capabilities/track.js

@@ -0,0 +1,331 @@
+/**
+ * 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 { CarrierError, serializeForLog } from '@shopickup/core';
+import { safeValidateTrackingRequest, safeValidateTrackingResponse, safeValidatePull500StartRequest, safeValidatePull500StartResponse, safeValidatePull500CheckRequest, safeValidatePull500CheckResponse, } from '../validation.js';
+import { mapMPLTrackingToCanonical, } from '../mappers/tracking.js';
+import { buildMPLHeaders } from '../utils/httpUtils.js';
+import { randomUUID } from 'crypto';
+/**
+ * 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 async function trackPull500Start(request, ctx, resolveTrackingUrl) {
+    // Validate request
+    const validation = safeValidatePull500StartRequest(request);
+    if (!validation.success) {
+        throw new CarrierError(`Invalid Pull-500 start request: ${validation.error.message}`, 'Validation', { raw: serializeForLog(validation.error) });
+    }
+    if (!ctx.http) {
+        throw new CarrierError('HTTP client not provided in context', 'Permanent');
+    }
+    const validRequest = validation.data;
+    // Resolve base URL and extract accounting code
+    const baseUrl = resolveTrackingUrl(validRequest.options);
+    const accountingCode = validRequest.credentials?.accountingCode;
+    const isTestApi = validRequest.options?.useTestApi ?? false;
+    ctx.logger?.debug('MPL: Pull-500 start', {
+        count: validRequest.trackingNumbers.length,
+        language: validRequest.language,
+        testMode: isTestApi,
+    });
+    // Build request payload
+    const payload = {
+        trackingNumbers: validRequest.trackingNumbers,
+        language: validRequest.language || 'hu',
+    };
+    // Build authentication headers with request ID and correlation ID
+    const headers = {
+        ...buildMPLHeaders(validRequest.credentials, accountingCode),
+        'X-Request-Id': randomUUID(),
+        'Content-Type': 'application/json',
+    };
+    // Add correlation ID if needed (optional)
+    if (validRequest.options?.useTestApi) {
+        headers['X-Correlation-Id'] = `test-${Date.now()}`;
+    }
+    // Make request to Pull-500 start endpoint
+    let httpResponse;
+    try {
+        const url = new URL('/v2/mplapi-tracking/tracking', baseUrl);
+        httpResponse = await ctx.http.post(url.toString(), payload, { headers });
+    }
+    catch (error) {
+        throw translateTrackingError(error, `Pull-500 start for ${validRequest.trackingNumbers.length} items`);
+    }
+    // Extract body from normalized HttpResponse
+    const responseData = httpResponse.body;
+    // Validate response
+    const responseValidation = safeValidatePull500StartResponse(responseData);
+    if (!responseValidation.success) {
+        throw new CarrierError(`Invalid Pull-500 start response: ${responseValidation.error.message}`, 'Transient', { raw: serializeForLog(responseValidation.error) });
+    }
+    const validResponse = responseValidation.data;
+    if (!validResponse.trackingGUID) {
+        throw new CarrierError('Pull-500 start response missing trackingGUID', 'Transient', { raw: responseData });
+    }
+    ctx.logger?.info('MPL: Pull-500 start completed', {
+        trackingGUID: validResponse.trackingGUID,
+        submitted: validRequest.trackingNumbers.length,
+    });
+    return validResponse;
+}
+/**
+ * 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 async function trackPull500Check(request, ctx, resolveTrackingUrl) {
+    // Validate request
+    const validation = safeValidatePull500CheckRequest(request);
+    if (!validation.success) {
+        throw new CarrierError(`Invalid Pull-500 check request: ${validation.error.message}`, 'Validation', { raw: serializeForLog(validation.error) });
+    }
+    if (!ctx.http) {
+        throw new CarrierError('HTTP client not provided in context', 'Permanent');
+    }
+    const validRequest = validation.data;
+    // Resolve base URL and extract accounting code
+    const baseUrl = resolveTrackingUrl(validRequest.options);
+    const accountingCode = validRequest.credentials?.accountingCode;
+    const isTestApi = validRequest.options?.useTestApi ?? false;
+    ctx.logger?.debug('MPL: Pull-500 check', {
+        trackingGUID: validRequest.trackingGUID,
+        testMode: isTestApi,
+    });
+    // Build authentication headers with request ID
+    const headers = {
+        ...buildMPLHeaders(validRequest.credentials, accountingCode),
+        'X-Request-Id': randomUUID(),
+    };
+    // Make request to Pull-500 check endpoint
+    let httpResponse;
+    try {
+        const url = new URL(`/v2/mplapi-tracking/tracking/${validRequest.trackingGUID}`, baseUrl);
+        httpResponse = await ctx.http.get(url.toString(), { headers });
+    }
+    catch (error) {
+        throw translateTrackingError(error, `Pull-500 check for GUID ${validRequest.trackingGUID}`);
+    }
+    // Extract body from normalized HttpResponse
+    const responseData = httpResponse.body;
+    // Validate response
+    const responseValidation = safeValidatePull500CheckResponse(responseData);
+    if (!responseValidation.success) {
+        throw new CarrierError(`Invalid Pull-500 check response: ${responseValidation.error.message}`, 'Transient', { raw: serializeForLog(responseValidation.error) });
+    }
+    const validResponse = responseValidation.data;
+    ctx.logger?.info('MPL: Pull-500 check completed', {
+        status: validResponse.status,
+        hasReport: !!validResponse.report,
+    });
+    return validResponse;
+}
+/**
+ * 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 async function trackRegistered(request, ctx, resolveTrackingUrl) {
+    // Use core track() logic but force registered endpoint
+    return track({
+        ...request,
+        useRegisteredEndpoint: true,
+    }, ctx, resolveTrackingUrl);
+}
+/**
+ * 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 async function track(request, ctx, resolveTrackingUrl) {
+    // Validate request
+    const validation = safeValidateTrackingRequest(request);
+    if (!validation.success) {
+        throw new CarrierError(`Invalid tracking request: ${validation.error.message}`, 'Validation', { raw: serializeForLog(validation.error) });
+    }
+    if (!ctx.http) {
+        throw new CarrierError('HTTP client not provided in context', 'Permanent');
+    }
+    const validRequest = validation.data;
+    // Determine endpoint (guest vs registered)
+    const isRegistered = validRequest.useRegisteredEndpoint ?? false;
+    const endpoint = isRegistered ? 'registered' : 'guest';
+    // Build request payload.
+    // MPL Pull-1 API uses POST body fields:
+    // - ids: comma-separated string of tracking numbers
+    // - state: 'last' or 'all'
+    // - language: 'hu' | 'en' | 'de'
+    const idsParam = validRequest.trackingNumbers.join(',');
+    const stateParam = validRequest.state ?? 'last';
+    // Extract accountingCode from credentials
+    const accountingCode = validRequest.credentials?.accountingCode;
+    // Resolve base URL
+    const baseUrl = resolveTrackingUrl(validRequest.options);
+    const isTestApi = validRequest.options?.useTestApi ?? false;
+    ctx.logger?.debug('MPL: Tracking parcels', {
+        endpoint,
+        trackingNumbers: validRequest.trackingNumbers,
+        state: stateParam,
+        testMode: isTestApi,
+        registered: isRegistered,
+    });
+    // Build URL and JSON body payload.
+    // Ensure base URL is treated as a path prefix, not as a file segment.
+    const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const url = new URL(endpoint, normalizedBaseUrl);
+    const payload = {
+        ids: idsParam,
+        state: stateParam,
+        language: 'hu',
+    };
+    // Build authentication headers
+    const headers = buildMPLHeaders(validRequest.credentials, accountingCode);
+    // Make request
+    let httpResponse;
+    try {
+        httpResponse = await ctx.http.post(url.toString(), payload, { headers });
+    }
+    catch (error) {
+        throw translateTrackingError(error, idsParam);
+    }
+    // Extract body from normalized HttpResponse
+    const responseData = httpResponse.body;
+    // Validate response
+    const responseValidation = safeValidateTrackingResponse(responseData);
+    if (!responseValidation.success) {
+        throw new CarrierError(`Invalid tracking response: ${responseValidation.error.message}`, 'Transient', { raw: serializeForLog(responseValidation.error) });
+    }
+    const validResponse = responseValidation.data;
+    // Check for empty response (tracking not found)
+    const records = validResponse.trackAndTrace;
+    if (!records || records.length === 0) {
+        throw new CarrierError(`No tracking information found for: ${idsParam}`, 'NotFound');
+    }
+    // Convert records to canonical format
+    // If state='all', each record is a separate event in history
+    // If state='last', each record is just the latest event
+    const trackingUpdates = records.map((record, index) => {
+        try {
+            // For 'all' state, this would be more complex (multiple records per tracking number)
+            // For now, assume one record per tracking number
+            return mapMPLTrackingToCanonical(record, isRegistered);
+        }
+        catch (error) {
+            throw new CarrierError(`Failed to map tracking record ${index}: ${error instanceof Error ? error.message : String(error)}`, 'Transient', { raw: record });
+        }
+    });
+    ctx.logger?.info('MPL: Tracking completed', {
+        found: trackingUpdates.length,
+        requested: validRequest.trackingNumbers.length,
+    });
+    return trackingUpdates;
+}
+/**
+ * Translate MPL tracking errors to CarrierError
+ *
+ * @param error - Original error from HTTP client
+ * @param trackingIds - Tracking numbers being queried (for context)
+ * @returns CarrierError with appropriate category
+ */
+function translateTrackingError(error, trackingIds) {
+    // Check if it's an axios or fetch error
+    if (error && typeof error === 'object') {
+        const err = error;
+        // Handle HTTP status codes
+        if (typeof err.status === 'number' || typeof err.response?.status === 'number') {
+            const status = err.status ?? err.response?.status;
+            const statusText = err.statusText ?? err.response?.statusText ?? '';
+            const data = err.data ?? err.response?.data ?? {};
+            if (status === 400) {
+                // Bad request - validation error
+                return new CarrierError(`Bad request (400): ${statusText || getErrorMessage(data)}`, 'Validation');
+            }
+            else if (status === 401 || status === 403) {
+                // Authentication/authorization error
+                return new CarrierError(`${status === 401 ? 'Unauthorized (401)' : 'Forbidden (403)'}: Invalid credentials`, 'Auth');
+            }
+            else if (status === 404) {
+                // Not found
+                return new CarrierError(`Not found (404): Tracking information not available`, 'NotFound');
+            }
+            else if (status === 429) {
+                // Rate limited
+                const retryAfter = err.headers?.['retry-after'] ?? err.response?.headers?.['retry-after'];
+                const retryAfterMs = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
+                return new CarrierError(`Rate limited (429): Too many requests`, 'RateLimit', { retryAfterMs });
+            }
+            else if (status >= 500) {
+                // Server error - transient
+                return new CarrierError(`Server error (${status}): ${statusText}`, 'Transient');
+            }
+        }
+        // Network/timeout errors
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+            return new CarrierError(`Network error: ${err.message}`, 'Transient');
+        }
+    }
+    // Generic error
+    return new CarrierError(`Tracking error: ${error instanceof Error ? error.message : String(error)}`, 'Transient');
+}
+/**
+ * Extract error message from MPL API error response
+ */
+function getErrorMessage(data) {
+    if (data && typeof data === 'object') {
+        // Check for gateway error format
+        if (data.fault?.faultstring) {
+            return data.fault.faultstring;
+        }
+        // Check for other error formats
+        if (data.message) {
+            return data.message;
+        }
+        if (data.error) {
+            return typeof data.error === 'string' ? data.error : data.error.message || 'Unknown error';
+        }
+    }
+    return 'Unknown error';
+}

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { AdapterContext, Capability, CarrierAdapter, CarrierResource, CreateLabelRequest, CreateLabelResponse, CreateLabelsRequest, CreateLabelsResponse, CreateParcelRequest, CreateParcelsRequest, CreateParcelsResponse, TrackingRequest, TrackingUpdate, ShipmentDetailsRequest, ShipmentDetailsResponse, FetchPickupPointsRequest, FetchPickupPointsResponse } from '@shopickup/core';
+import { createResolveBaseUrl, createResolveOAuthUrl, ResolveBaseUrl, ResolveOAuthUrl } from './utils/resolveBaseUrl.js';
+import type { ExchangeAuthTokenRequest, ExchangeAuthTokenResponse } from './validation.js';
+/**
+ * MPLAdapter
+ *
+ * MPL (hu-mpl) 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
+ * - CLOSE_SHIPMENTS: Closes shipments to finalize them before sendoff.
+ * - TRACK: Track parcels by barcode
+ * - EXCHANGE_AUTH_TOKEN: Exchange API credentials for OAuth2 Bearer token
+ * - TEST_MODE_SUPPORTED: Can switch to test API for sandbox testing
+ *
+ * Test API:
+ * - Production: 	https://core.api.posta.hu/v2/mplapi
+ * - Test/Sandbox: 	https://sandbox.api.posta.hu/v2/mplapi
+ * - Pass options.useTestApi = true in request to switch to test endpoint for that call
+ * - Test API requires separate test credentials
+ *
+ * OAuth Token Exchange:
+ * - Call exchangeAuthToken() to exchange API credentials for a Bearer token
+ * - Cached internally within the adapter; TTL is ~1 hour
+ * - Returns access_token, expires_in, and token_type
+ * - Useful when Basic auth is disabled at account level
+ *
+ * OAuth Fallback:
+ * - Wrap HTTP client with withOAuthFallback() to automatically exchange credentials
+ *   when receiving 401 "Basic auth not enabled" error
+ * - No explicit calls needed; fallback is transparent
+ *
+ * Notes:
+ * - MPL 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 MPLAdapter implements CarrierAdapter {
+    readonly id = "hu-mpl";
+    readonly displayName = "MPL Hungary";
+    readonly capabilities: Capability[];
+    readonly requires: {
+        createLabel: ("CREATE_PARCEL" | "CLOSE_SHIPMENT")[];
+    };
+    private prodBaseUrl;
+    private testBaseUrl;
+    private prodOAuthUrl;
+    private testOAuthUrl;
+    private prodTrackingUrl;
+    private testTrackingUrl;
+    private resolveBaseUrl;
+    private resolveOAuthUrl;
+    private resolveTrackingUrl;
+    private accountingCode;
+    constructor(baseUrl?: string, accountingCode?: string);
+    /**
+     * Create a single parcel in MPL
+     */
+    createParcel(req: CreateParcelRequest, ctx: AdapterContext): Promise<CarrierResource>;
+    /**
+     * Create multiple parcels in MPL (batch operation)
+     */
+    createParcels(req: CreateParcelsRequest, ctx: AdapterContext): Promise<CreateParcelsResponse>;
+    createLabel(req: CreateLabelRequest, ctx: AdapterContext): Promise<CreateLabelResponse>;
+    createLabels(req: CreateLabelsRequest, ctx: AdapterContext): Promise<CreateLabelsResponse>;
+    track(req: TrackingRequest, ctx: AdapterContext): Promise<TrackingUpdate>;
+    getShipmentDetails(req: ShipmentDetailsRequest, ctx: AdapterContext): Promise<ShipmentDetailsResponse>;
+    exchangeAuthToken(req: ExchangeAuthTokenRequest, ctx: AdapterContext): Promise<ExchangeAuthTokenResponse>;
+    fetchPickupPoints(req: FetchPickupPointsRequest, ctx: AdapterContext): Promise<FetchPickupPointsResponse>;
+    /**
+     * Close shipments (batch) - delegates to capability implementation
+     */
+    closeShipments(req: import('@shopickup/core').CloseShipmentsRequest, ctx: AdapterContext): Promise<import('@shopickup/core').CloseShipmentsResponse>;
+}
+export { withOAuthFallback } from './utils/oauthFallback.js';
+export { createResolveBaseUrl, createResolveOAuthUrl };
+export type { ResolveBaseUrl, ResolveOAuthUrl };
+export { track, trackPull500Start, trackPull500Check, trackRegistered } from './capabilities/track.js';
+export * 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,OAAO,EAAE,cAAc,EAAgB,UAAU,EAAE,cAAc,EAAgB,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,cAAc,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACvZ,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAA4B,cAAc,EAAE,eAAe,EAAsB,MAAM,2BAA2B,CAAC;AAOvK,OAAO,KAAK,EAAkG,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE3L;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC7C,QAAQ,CAAC,EAAE,YAAY;IACvB,QAAQ,CAAC,WAAW,iBAAiB;IAErC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,CASjC;IAGF,QAAQ,CAAC,QAAQ;;MAEhB;IAED,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,WAAW,CAA4C;IAC/D,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,eAAe,CAAiD;IACxE,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,cAAc,CAAc;gBAExB,OAAO,GAAE,MAA8C,EAAE,cAAc,GAAE,MAAW;IAahG;;OAEG;IACG,YAAY,CACd,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC;IAQ3B;;OAEG;IACG,aAAa,CACf,GAAG,EAAE,oBAAoB,EACzB,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,qBAAqB,CAAC;IAI3B,WAAW,CACb,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAIzB,YAAY,CACd,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,oBAAoB,CAAC;IAI1B,KAAK,CACP,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,CAAC;IAuBpB,kBAAkB,CACpB,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,uBAAuB,CAAC;IAI7B,iBAAiB,CACnB,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,yBAAyB,CAAC;IAI/B,iBAAiB,CACnB,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,yBAAyB,CAAC;IAIrC;;OAEG;IACG,cAAc,CAChB,GAAG,EAAE,OAAO,iBAAiB,EAAE,qBAAqB,EACpD,GAAG,EAAE,cAAc,GACpB,OAAO,CAAC,OAAO,iBAAiB,EAAE,sBAAsB,CAAC;CAK/D;AAGD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEvG,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,142 @@
+import { Capabilities, CarrierError } from '@shopickup/core';
+import { createResolveBaseUrl, createResolveOAuthUrl, createResolveTrackingUrl } from './utils/resolveBaseUrl.js';
+import { fetchPickupPoints as fetchPickupPointsImpl } from './capabilities/index.js';
+import { getShipmentDetails as getShipmentDetailsImpl } from './capabilities/get-shipment-details.js';
+import { track as trackImpl } from './capabilities/track.js';
+import { exchangeAuthToken as exchangeAuthTokenImpl } from './capabilities/auth.js';
+import { createParcel as createParcelImpl, createParcels as createParcelsImpl } from './capabilities/parcels.js';
+import { createLabel as createLabelImpl, createLabels as createLabelsImpl } from './capabilities/label.js';
+/**
+ * MPLAdapter
+ *
+ * MPL (hu-mpl) 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
+ * - CLOSE_SHIPMENTS: Closes shipments to finalize them before sendoff.
+ * - TRACK: Track parcels by barcode
+ * - EXCHANGE_AUTH_TOKEN: Exchange API credentials for OAuth2 Bearer token
+ * - TEST_MODE_SUPPORTED: Can switch to test API for sandbox testing
+ *
+ * Test API:
+ * - Production: 	https://core.api.posta.hu/v2/mplapi
+ * - Test/Sandbox: 	https://sandbox.api.posta.hu/v2/mplapi
+ * - Pass options.useTestApi = true in request to switch to test endpoint for that call
+ * - Test API requires separate test credentials
+ *
+ * OAuth Token Exchange:
+ * - Call exchangeAuthToken() to exchange API credentials for a Bearer token
+ * - Cached internally within the adapter; TTL is ~1 hour
+ * - Returns access_token, expires_in, and token_type
+ * - Useful when Basic auth is disabled at account level
+ *
+ * OAuth Fallback:
+ * - Wrap HTTP client with withOAuthFallback() to automatically exchange credentials
+ *   when receiving 401 "Basic auth not enabled" error
+ * - No explicit calls needed; fallback is transparent
+ *
+ * Notes:
+ * - MPL 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 MPLAdapter {
+    id = "hu-mpl";
+    displayName = "MPL Hungary";
+    capabilities = [
+        Capabilities.CREATE_PARCEL,
+        Capabilities.CREATE_PARCELS,
+        Capabilities.CREATE_LABEL,
+        Capabilities.TRACK,
+        Capabilities.GET_SHIPMENT_DETAILS,
+        Capabilities.CLOSE_SHIPMENT,
+        Capabilities.TEST_MODE_SUPPORTED,
+        Capabilities.EXCHANGE_AUTH_TOKEN,
+    ];
+    // MPL requires close before label generation
+    requires = {
+        createLabel: [Capabilities.CREATE_PARCEL, Capabilities.CLOSE_SHIPMENT],
+    };
+    prodBaseUrl = "https://core.api.posta.hu/v2/mplapi";
+    testBaseUrl = "https://sandbox.api.posta.hu/v2/mplapi";
+    prodOAuthUrl = "https://core.api.posta.hu/oauth2/token";
+    testOAuthUrl = "https://sandbox.api.posta.hu/oauth2/token";
+    prodTrackingUrl = "https://core.api.posta.hu/v2/nyomkovetes";
+    testTrackingUrl = "https://sandbox.api.posta.hu/v2/nyomkovetes";
+    resolveBaseUrl;
+    resolveOAuthUrl;
+    resolveTrackingUrl;
+    accountingCode = "";
+    constructor(baseUrl = "https://core.api.posta.hu/v2/mplapi", accountingCode = "") {
+        this.prodBaseUrl = "https://core.api.posta.hu/v2/mplapi";
+        this.testBaseUrl = "https://sandbox.api.posta.hu/v2/mplapi";
+        this.prodOAuthUrl = "https://core.api.posta.hu/oauth2/token";
+        this.testOAuthUrl = "https://sandbox.api.posta.hu/oauth2/token";
+        this.prodTrackingUrl = "https://core.api.posta.hu/v2/nyomkovetes";
+        this.testTrackingUrl = "https://sandbox.api.posta.hu/v2/nyomkovetes";
+        this.resolveBaseUrl = createResolveBaseUrl(this.prodBaseUrl, this.testBaseUrl);
+        this.resolveOAuthUrl = createResolveOAuthUrl(this.prodOAuthUrl, this.testOAuthUrl);
+        this.resolveTrackingUrl = createResolveTrackingUrl(this.prodTrackingUrl, this.testTrackingUrl);
+        this.accountingCode = accountingCode;
+    }
+    /**
+     * Create a single parcel in MPL
+     */
+    async createParcel(req, ctx) {
+        return createParcelImpl(req, ctx, (batchReq, batchCtx) => this.createParcels(batchReq, batchCtx));
+    }
+    /**
+     * Create multiple parcels in MPL (batch operation)
+     */
+    async createParcels(req, ctx) {
+        return createParcelsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    async createLabel(req, ctx) {
+        return createLabelImpl(req, ctx, this.resolveBaseUrl);
+    }
+    async createLabels(req, ctx) {
+        return createLabelsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    async track(req, ctx) {
+        // MPL supports batch tracking, but core interface expects single TrackingUpdate
+        // Convert single TrackingRequest to internal batch format and return first result
+        const batchRequest = {
+            trackingNumbers: [req.trackingNumber],
+            credentials: (req.credentials || {}),
+            state: 'last',
+            useRegisteredEndpoint: false,
+            options: req.options,
+        };
+        const results = await trackImpl(batchRequest, ctx, this.resolveTrackingUrl);
+        if (results.length === 0) {
+            throw new CarrierError(`No tracking information found for: ${req.trackingNumber}`, 'NotFound');
+        }
+        return results[0];
+    }
+    async getShipmentDetails(req, ctx) {
+        return getShipmentDetailsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    async exchangeAuthToken(req, ctx) {
+        return exchangeAuthTokenImpl(req, ctx, this.resolveOAuthUrl, this.accountingCode);
+    }
+    async fetchPickupPoints(req, ctx) {
+        return fetchPickupPointsImpl(req, ctx, this.resolveBaseUrl);
+    }
+    /**
+     * Close shipments (batch) - delegates to capability implementation
+     */
+    async closeShipments(req, ctx) {
+        // Lazy import to avoid circular deps in some test environments
+        const { closeShipments: closeImpl } = await import('./capabilities/index.js');
+        return closeImpl(req, ctx, this.resolveBaseUrl);
+    }
+}
+// Export utilities for use with dev server or other integrations
+export { withOAuthFallback } from './utils/oauthFallback.js';
+export { createResolveBaseUrl, createResolveOAuthUrl };
+export { track, trackPull500Start, trackPull500Check, trackRegistered } from './capabilities/track.js';
+// Re-export validation helpers for consumers (dev-server uses these)
+export * from './validation.js';

package/dist/mappers/label.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Label mapping utilities for MPL adapter
+ *
+ * Handles conversion from canonical label requests to MPL API query parameters
+ * and normalization of API responses back to canonical format.
+ *
+ * The MPL label endpoint uses GET with query parameters:
+ * GET /shipments/label?trackingNumbers=X&trackingNumbers=Y&labelType=A5&labelFormat=PDF&orderBy=SENDING&singleFile=true
+ *
+ * Response is JSON array of LabelQueryResult objects with base64-encoded label data.
+ */
+import type { CreateLabelsMPLRequest, CreateLabelsMPLOptions, LabelOrderBy, LabelFormat, LabelType } from '../validation.js';
+type CreateLabelsMPLRequestWithOptions = Omit<CreateLabelsMPLRequest, 'options'> & {
+    options: CreateLabelsMPLOptions;
+};
+/**
+ * Query parameters for the MPL label API GET request
+ */
+export interface LabelQueryParams {
+    trackingNumbers: string[];
+    labelType?: LabelType;
+    labelFormat?: LabelFormat;
+    orderBy?: LabelOrderBy;
+    singleFile?: boolean;
+}
+/**
+ * Build query parameters from canonical label request
+ *
+ * Transforms CreateLabelsMPLRequest into query parameters suitable for
+ * the MPL GET /shipments/label endpoint.
+ *
+ * @param req - Canonical label request
+ * @returns Query parameters object
+ */
+export declare function buildLabelQueryParams(req: CreateLabelsMPLRequestWithOptions): LabelQueryParams;
+/**
+ * Serialize query parameters to URL search params string
+ *
+ * Handles array parameters (trackingNumbers) as multiple query params:
+ * ?trackingNumbers=X&trackingNumbers=Y&trackingNumbers=Z&labelType=A5&labelFormat=PDF
+ *
+ * @param params - Query parameters
+ * @returns URLSearchParams string (without leading ?)
+ */
+export declare function serializeQueryParams(params: LabelQueryParams): string;
+/**
+ * Build complete query string for logging/debugging
+ *
+ * Shows the actual query string that will be sent to the API
+ *
+ * @param params - Query parameters
+ * @returns Complete query string with leading ?
+ */
+export declare function buildQueryString(params: LabelQueryParams): string;
+/**
+ * Get default values for optional label parameters
+ *
+ * These match MPL server defaults for when parameters are not specified
+ */
+export declare const LABEL_DEFAULTS: {
+    labelType: "A5";
+    labelFormat: "PDF";
+    orderBy: undefined;
+    singleFile: boolean;
+};
+export {};
+//# sourceMappingURL=label.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../src/mappers/label.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,SAAS,EACV,MAAM,kBAAkB,CAAC;AAE1B,KAAK,iCAAiC,GAAG,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,GAAG;IACjF,OAAO,EAAE,sBAAsB,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iCAAiC,GAAG,gBAAgB,CAS9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAuBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAGjE;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;CAK1B,CAAC"}