@shopickup/adapters-mpl 0.0.1

package/dist/mappers/tracking.js

@@ -0,0 +1,187 @@
+/**
+ * MPL Tracking Mapper
+ * Converts MPL C-code tracking records to canonical TrackingUpdate format
+ */
+/**
+ * Map MPL tracking status codes (C9) to canonical TrackingStatus
+ *
+ * C9 contains the tracking status code in Hungarian.
+ * Common values (from carrier documentation):
+ * - BEÉRKEZETT / RECEIVED / etc.
+ */
+function mapStatusCode(c9) {
+    if (!c9)
+        return 'PENDING';
+    const statusMap = {
+        // Hungarian versions
+        'BEÉRKEZETT': 'PENDING',
+        'FELDOLGOZÁS': 'PENDING',
+        'SZÁLLÍTÁS': 'IN_TRANSIT',
+        'KÉZBESÍTÉS_ALATT': 'OUT_FOR_DELIVERY',
+        'KÉZBESÍTVE': 'DELIVERED',
+        'VISSZAKÜLDVE': 'RETURNED',
+        'HIBA': 'EXCEPTION',
+        'FELDOLGOZÁS ALATT': 'PENDING',
+        'CSOMAG FELDOLGOZÁSA ALATT': 'PENDING',
+        // English versions
+        'RECEIVED': 'PENDING',
+        'PROCESSING': 'PENDING',
+        'IN_TRANSIT': 'IN_TRANSIT',
+        'IN_DELIVERY': 'OUT_FOR_DELIVERY',
+        'OUT_FOR_DELIVERY': 'OUT_FOR_DELIVERY',
+        'DELIVERED': 'DELIVERED',
+        'RETURNED': 'RETURNED',
+        'ERROR': 'EXCEPTION',
+        'EXCEPTION': 'EXCEPTION',
+        'PENDING': 'PENDING',
+        // German versions
+        'EMPFANGEN': 'PENDING',
+        'VERARBEITUNG': 'PENDING',
+        'TRANSPORT': 'IN_TRANSIT',
+        'AUSLIEFERUNG': 'OUT_FOR_DELIVERY',
+        'GELIEFERT': 'DELIVERED',
+        'ZURÜCKGEGEBEN': 'RETURNED',
+        'FEHLER': 'EXCEPTION',
+    };
+    return statusMap[c9.toUpperCase().trim()] || 'PENDING';
+}
+/**
+ * Parse date/time from MPL format
+ * Expects format like: "2025-01-27 14:30:00" or similar
+ */
+function parseTimestamp(timestamp) {
+    if (!timestamp)
+        return null;
+    try {
+        const parsed = new Date(timestamp);
+        if (!isNaN(parsed.getTime())) {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Parse weight from string (C5)
+ * Expects format like "1.5 kg" or "1500" (grams)
+ */
+function parseWeight(weightStr) {
+    if (!weightStr)
+        return undefined;
+    try {
+        // Remove units (kg, g, etc.)
+        const numStr = weightStr.replace(/[^\d.,]/g, '').replace(',', '.');
+        const weight = parseFloat(numStr);
+        return isNaN(weight) ? undefined : weight;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build event history from a single C-code record
+ * For 'last' state, returns single event from latest status
+ * For 'all' state, caller is responsible for handling multiple records
+ */
+function buildTrackingEvent(record) {
+    const timestamp = parseTimestamp(record.c10) || new Date();
+    const status = mapStatusCode(record.c9);
+    // Build location object from C-codes
+    const location = (record.c8 || record.c11) ? {
+        city: record.c11 || record.c8,
+    } : undefined;
+    return {
+        timestamp,
+        status,
+        location,
+        description: record.c12 || record.c6 || 'No description',
+        carrierStatusCode: record.c9,
+        raw: record,
+    };
+}
+/**
+ * Convert MPL C-code tracking record to canonical TrackingUpdate
+ *
+ * @param record - MPL tracking record with C-codes
+ * @param includeFinancialData - If true, include weight/size/value (Registered endpoint)
+ * @returns Canonical TrackingUpdate
+ */
+export function mapMPLTrackingToCanonical(record, includeFinancialData = false) {
+    // Validate critical field
+    if (!record.c1) {
+        throw new Error('Invalid tracking record: missing c1 (Consignment ID)');
+    }
+    // Build base tracking update
+    const trackingUpdate = {
+        trackingNumber: record.c1,
+        status: mapStatusCode(record.c9),
+        lastUpdate: parseTimestamp(record.c10) || null,
+        events: [buildTrackingEvent(record)],
+        rawCarrierResponse: {
+            record,
+            // Include financial data in response if available
+            ...(includeFinancialData && {
+                weight: record.c5,
+                dimensions: {
+                    length: record.c41,
+                    width: record.c42,
+                    height: record.c43,
+                },
+                value: record.c58,
+            }),
+        },
+    };
+    return trackingUpdate;
+}
+/**
+ * Build multiple events from complete tracking history
+ * Used when state='all' is requested
+ *
+ * Note: MPL API appears to return multiple records in trackAndTrace array
+ * when state='all'. Each record represents an event in the history.
+ */
+export function mapMPLTrackingHistoryToCanonical(records, includeFinancialData = false) {
+    if (records.length === 0) {
+        throw new Error('No tracking records provided');
+    }
+    // Get base info from first/main record (usually latest)
+    const mainRecord = records[0];
+    const trackingNumber = mainRecord.c1;
+    if (!trackingNumber) {
+        throw new Error('Invalid tracking records: missing c1 (Consignment ID)');
+    }
+    // Build event history from all records
+    const events = records.map(record => buildTrackingEvent(record));
+    // Get latest status from first record (most recent)
+    const latestStatus = mapStatusCode(mainRecord.c9);
+    const lastUpdate = parseTimestamp(mainRecord.c10) || null;
+    const trackingUpdate = {
+        trackingNumber,
+        status: latestStatus,
+        lastUpdate,
+        events,
+        rawCarrierResponse: {
+            records,
+            // Include financial data in response if available
+            ...(includeFinancialData && {
+                weight: mainRecord.c5,
+                dimensions: {
+                    length: mainRecord.c41,
+                    width: mainRecord.c42,
+                    height: mainRecord.c43,
+                },
+                value: mainRecord.c58,
+            }),
+        },
+    };
+    return trackingUpdate;
+}
+/**
+ * Determine if record has financial data (Registered vs Guest)
+ * Registered includes C5 (weight), Guest excludes it
+ */
+export function isRegisteredRecord(record) {
+    return !!(record.c5 || record.c41 || record.c42 || record.c58);
+}

package/dist/utils/httpUtils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MPL HTTP Client Utilities
+ * Thin utilities for building MPL API requests
+ */
+import type { MPLCredentials } from '../validation.js';
+/**
+ * Build standard MPL auth headers
+ * Supports both OAuth2 Bearer token and API Key authentication
+ * Uses "Authorization" header with appropriate scheme
+ *
+ * @param credentials MPL credentials (OAuth2 or API Key)
+ * @param accountingCode Customer code provided by Magyar Posta Zrt.
+ * @param requestId Optional GUID for request tracking; auto-generated if omitted
+ * @returns Headers object with Authorization, Content-Type, X-Accounting-Code, and X-Request-ID
+ */
+export declare function buildMPLHeaders(credentials: MPLCredentials, accountingCode: string, requestId?: string): Record<string, string>;
+/**
+ * Check if an error response indicates Basic authentication is disabled
+ *
+ * When Basic auth is disabled at the MPL account level, the API returns a 401 with:
+ * {
+ *   "fault": {
+ *     "faultstring": "Basic authentication is not enabled for this proxy or client.",
+ *     "detail": {
+ *       "errorcode": "RaiseFault.BasicAuthNotEnabled"
+ *     }
+ *   }
+ * }
+ *
+ * This helper detects this specific error to trigger OAuth token exchange fallback.
+ *
+ * @param body Response body (likely parsed JSON)
+ * @returns true if the error is "Basic auth not enabled"
+ */
+export declare function isBasicAuthDisabledError(body: unknown): boolean;
+//# sourceMappingURL=httpUtils.d.ts.map

package/dist/utils/httpUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpUtils.d.ts","sourceRoot":"","sources":["../../src/utils/httpUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,EAA8B,MAAM,kBAAkB,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,WAAW,EAAE,cAAc,EAC3B,cAAc,EAAE,MAAM,EACtB,SAAS,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAkB/D"}

package/dist/utils/httpUtils.js

@@ -0,0 +1,76 @@
+/**
+ * MPL HTTP Client Utilities
+ * Thin utilities for building MPL API requests
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Build standard MPL auth headers
+ * Supports both OAuth2 Bearer token and API Key authentication
+ * Uses "Authorization" header with appropriate scheme
+ *
+ * @param credentials MPL credentials (OAuth2 or API Key)
+ * @param accountingCode Customer code provided by Magyar Posta Zrt.
+ * @param requestId Optional GUID for request tracking; auto-generated if omitted
+ * @returns Headers object with Authorization, Content-Type, X-Accounting-Code, and X-Request-ID
+ */
+export function buildMPLHeaders(credentials, accountingCode, requestId) {
+    const authType = credentials.authType;
+    const guid = requestId || randomUUID();
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    // Add X-Request-ID (required by MPL API)
+    headers["X-Request-ID"] = guid;
+    // Add X-Accounting-Code if provided
+    if (accountingCode) {
+        headers["X-Accounting-Code"] = accountingCode;
+    }
+    // Add Authorization header based on auth type
+    if (authType === 'oauth2') {
+        const { oAuth2Token } = credentials;
+        headers["Authorization"] = `Bearer ${oAuth2Token}`;
+    }
+    else if (authType === 'apiKey') {
+        const { apiKey, apiSecret } = credentials;
+        const basicAuth = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");
+        headers["Authorization"] = `Basic ${basicAuth}`;
+    }
+    else {
+        // This should never happen due to type safety, but added for completeness
+        throw new Error(`Unsupported MPL auth type: ${authType}`);
+    }
+    return headers;
+}
+/**
+ * Check if an error response indicates Basic authentication is disabled
+ *
+ * When Basic auth is disabled at the MPL account level, the API returns a 401 with:
+ * {
+ *   "fault": {
+ *     "faultstring": "Basic authentication is not enabled for this proxy or client.",
+ *     "detail": {
+ *       "errorcode": "RaiseFault.BasicAuthNotEnabled"
+ *     }
+ *   }
+ * }
+ *
+ * This helper detects this specific error to trigger OAuth token exchange fallback.
+ *
+ * @param body Response body (likely parsed JSON)
+ * @returns true if the error is "Basic auth not enabled"
+ */
+export function isBasicAuthDisabledError(body) {
+    if (!body || typeof body !== 'object')
+        return false;
+    const gatewayError = body;
+    const fault = gatewayError.fault;
+    if (!fault || typeof fault !== 'object')
+        return false;
+    const faultString = fault.faultstring || '';
+    const errorCode = fault.detail?.errorcode || '';
+    // Check for the specific error message
+    const hasBasicAuthMessage = typeof faultString === 'string' &&
+        faultString.includes('Basic authentication is not enabled');
+    const hasBasicAuthCode = errorCode === 'RaiseFault.BasicAuthNotEnabled';
+    return hasBasicAuthMessage || hasBasicAuthCode;
+}

package/dist/utils/oauthFallback.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OAuth Fallback HTTP Client Wrapper
+ *
+ * Wraps an HTTP client to automatically handle the case where Basic auth is disabled
+ * at the MPL account level. When a 401 is received with the "Basic auth not enabled" error,
+ * this wrapper:
+ *
+ * 1. Exchanges API credentials for an OAuth2 Bearer token
+ * 2. Retries the original request with the new Bearer token
+ * 3. Returns the retried response
+ *
+ * This allows integrators to use Basic auth normally, but automatically falls back
+ * to OAuth when Basic auth is not available, without modifying adapter code.
+ *
+ * Pattern:
+ * ```typescript
+ * const baseHttpClient = createAxiosHttpClient();
+ * const wrappedHttpClient = withOAuthFallback(
+ *   baseHttpClient,
+ *   credentials,
+ *   accountingCode,
+ *   resolveOAuthUrl,
+ *   logger
+ * );
+ * // Now calls to wrappedHttpClient.post(...) handle OAuth fallback automatically
+ * ```
+ */
+import type { HttpClient } from "@shopickup/core";
+import type { Logger } from "@shopickup/core";
+import type { MPLCredentials } from "../validation.js";
+import type { ResolveOAuthUrl } from "./resolveBaseUrl.js";
+/**
+ * Create an HTTP client wrapper that automatically exchanges credentials
+ * to OAuth2 Bearer token when Basic auth is disabled
+ *
+ * @param baseHttpClient The underlying HTTP client to wrap
+ * @param credentials API credentials (apiKey + apiSecret for Basic auth)
+ * @param accountingCode Customer code from Magyar Posta
+ * @param resolveOAuthUrl Function to resolve OAuth token endpoint URL (test vs. production)
+ * @param logger Optional logger for debugging
+ * @param useTestApi Optional flag to use sandbox/test API for OAuth token exchange (defaults to false/production)
+ * @returns Wrapped HttpClient with OAuth fallback
+ */
+export declare function withOAuthFallback(baseHttpClient: HttpClient, credentials: Extract<MPLCredentials, {
+    authType: 'apiKey';
+}>, accountingCode: string, resolveOAuthUrl: ResolveOAuthUrl, logger?: Logger, useTestApi?: boolean): HttpClient;
+//# sourceMappingURL=oauthFallback.d.ts.map

package/dist/utils/oauthFallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthFallback.d.ts","sourceRoot":"","sources":["../../src/utils/oauthFallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,iBAAiB,CAAC;AAElF,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAA6B,MAAM,kBAAkB,CAAC;AAGlF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAkB3D;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,UAAU,EAC1B,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,EAC5D,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,eAAe,EAChC,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,GAAE,OAAe,GAC1B,UAAU,CA4OZ"}

package/dist/utils/oauthFallback.js

@@ -0,0 +1,250 @@
+/**
+ * OAuth Fallback HTTP Client Wrapper
+ *
+ * Wraps an HTTP client to automatically handle the case where Basic auth is disabled
+ * at the MPL account level. When a 401 is received with the "Basic auth not enabled" error,
+ * this wrapper:
+ *
+ * 1. Exchanges API credentials for an OAuth2 Bearer token
+ * 2. Retries the original request with the new Bearer token
+ * 3. Returns the retried response
+ *
+ * This allows integrators to use Basic auth normally, but automatically falls back
+ * to OAuth when Basic auth is not available, without modifying adapter code.
+ *
+ * Pattern:
+ * ```typescript
+ * const baseHttpClient = createAxiosHttpClient();
+ * const wrappedHttpClient = withOAuthFallback(
+ *   baseHttpClient,
+ *   credentials,
+ *   accountingCode,
+ *   resolveOAuthUrl,
+ *   logger
+ * );
+ * // Now calls to wrappedHttpClient.post(...) handle OAuth fallback automatically
+ * ```
+ */
+import { CarrierError } from "@shopickup/core";
+import { exchangeAuthToken } from "../capabilities/auth.js";
+import { isBasicAuthDisabledError, buildMPLHeaders } from "./httpUtils.js";
+/**
+ * Check if an error is an HttpError with 401 "Basic auth disabled" status
+ */
+function isBasicAuthDisabledHttpError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const errObj = err;
+    // Check if it's an HTTP error with 401 status
+    // HttpError has structure: { status?: number, response?: { data: unknown } }
+    if (errObj.status === 401 && errObj.response?.data) {
+        return isBasicAuthDisabledError(errObj.response.data);
+    }
+    return false;
+}
+/**
+ * Create an HTTP client wrapper that automatically exchanges credentials
+ * to OAuth2 Bearer token when Basic auth is disabled
+ *
+ * @param baseHttpClient The underlying HTTP client to wrap
+ * @param credentials API credentials (apiKey + apiSecret for Basic auth)
+ * @param accountingCode Customer code from Magyar Posta
+ * @param resolveOAuthUrl Function to resolve OAuth token endpoint URL (test vs. production)
+ * @param logger Optional logger for debugging
+ * @param useTestApi Optional flag to use sandbox/test API for OAuth token exchange (defaults to false/production)
+ * @returns Wrapped HttpClient with OAuth fallback
+ */
+export function withOAuthFallback(baseHttpClient, credentials, accountingCode, resolveOAuthUrl, logger, useTestApi = false) {
+    let cachedOAuthToken = null;
+    /**
+     * Internal helper to handle 401 "Basic auth disabled" error
+     * Exchanges credentials for OAuth token and retries the request
+     */
+    async function handleBasicAuthDisabled(method, url, data, config) {
+        try {
+            logger?.info('[OAuth Fallback] Basic auth disabled detected, attempting to exchange credentials', {
+                url,
+                method,
+                accountingCode: accountingCode.substring(0, 4) + '****' // mask for logging
+            });
+            // Exchange credentials for OAuth token (or use cached token)
+            let oauthToken;
+            if (cachedOAuthToken && cachedOAuthToken.issued_at) {
+                // Check if token is still valid (with 30-second buffer)
+                const expiresAt = cachedOAuthToken.issued_at + (cachedOAuthToken.expires_in * 1000) - 30000;
+                if (Date.now() < expiresAt) {
+                    logger?.debug('[OAuth Fallback] Using cached OAuth token', {
+                        expiresInSeconds: cachedOAuthToken.expires_in,
+                        remainingMs: expiresAt - Date.now(),
+                    });
+                    oauthToken = cachedOAuthToken.access_token;
+                }
+                else {
+                    logger?.info('[OAuth Fallback] Cached OAuth token expired, exchanging for new one', {
+                        expiresInSeconds: cachedOAuthToken.expires_in,
+                    });
+                    // Token expired, exchange again
+                    const exchanged = await exchangeAuthToken({ credentials, options: { useTestApi } }, { http: baseHttpClient, logger }, resolveOAuthUrl, accountingCode);
+                    logger?.info('[OAuth Fallback] Successfully exchanged credentials for new OAuth token', {
+                        expiresInSeconds: exchanged.expires_in,
+                    });
+                    cachedOAuthToken = exchanged;
+                    oauthToken = exchanged.access_token;
+                }
+            }
+            else {
+                // No cached token, exchange now
+                logger?.info('[OAuth Fallback] No cached token, exchanging API credentials for OAuth token');
+                const exchanged = await exchangeAuthToken({ credentials, options: { useTestApi } }, { http: baseHttpClient, logger }, resolveOAuthUrl, accountingCode);
+                logger?.info('[OAuth Fallback] Successfully exchanged credentials for OAuth token', {
+                    expiresInSeconds: exchanged.expires_in,
+                });
+                cachedOAuthToken = exchanged;
+                oauthToken = exchanged.access_token;
+            }
+            // Build new headers with OAuth token using object literal with 'any' type
+            // to work around TypeScript's discriminated union inference issue
+            const oauthCredentialsObj = {
+                authType: 'oauth2',
+                oAuth2Token: oauthToken,
+            };
+            const newHeaders = {
+                ...(config?.headers || {}),
+                ...buildMPLHeaders(oauthCredentialsObj, accountingCode),
+            };
+            const newConfig = {
+                ...config,
+                headers: newHeaders,
+            };
+            logger?.info('[OAuth Fallback] Retrying original request with OAuth Bearer token', {
+                url,
+                method
+            });
+            // Retry the original request with new OAuth credentials
+            const retryResponse = await baseHttpClient[method](url, data, newConfig);
+            logger?.info('[OAuth Fallback] Request succeeded after OAuth fallback', {
+                url,
+                method,
+                status: retryResponse.status
+            });
+            return retryResponse;
+        }
+        catch (err) {
+            // OAuth exchange failed or retry failed
+            // Fail-fast: don't retry again
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            logger?.error('[OAuth Fallback] OAuth fallback failed', {
+                url,
+                method,
+                error: errorMessage,
+                errorType: err instanceof Error ? err.constructor.name : typeof err,
+            });
+            if (err instanceof CarrierError) {
+                throw err;
+            }
+            throw new CarrierError(`OAuth fallback failed: ${errorMessage}`, 'Transient', { raw: err });
+        }
+    }
+    return {
+        async get(url, config) {
+            try {
+                const response = await baseHttpClient.get(url, config);
+                // Check for "Basic auth disabled" error in successful response
+                if (response.status === 401 && isBasicAuthDisabledError(response.body)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 response (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('get', url, undefined, config);
+                }
+                return response;
+            }
+            catch (err) {
+                // Check if error is a 401 "Basic auth disabled" error
+                if (isBasicAuthDisabledHttpError(err)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 error (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('get', url, undefined, config);
+                }
+                // Re-throw other errors
+                throw err;
+            }
+        },
+        async post(url, data, config) {
+            try {
+                const response = await baseHttpClient.post(url, data, config);
+                // Check for "Basic auth disabled" error in successful response
+                if (response.status === 401 && isBasicAuthDisabledError(response.body)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 response (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('post', url, data, config);
+                }
+                return response;
+            }
+            catch (err) {
+                // Check if error is a 401 "Basic auth disabled" error
+                if (isBasicAuthDisabledHttpError(err)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 error (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('post', url, data, config);
+                }
+                // Re-throw other errors
+                throw err;
+            }
+        },
+        async put(url, data, config) {
+            try {
+                const response = await baseHttpClient.put(url, data, config);
+                // Check for "Basic auth disabled" error in successful response
+                if (response.status === 401 && isBasicAuthDisabledError(response.body)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 response (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('put', url, data, config);
+                }
+                return response;
+            }
+            catch (err) {
+                // Check if error is a 401 "Basic auth disabled" error
+                if (isBasicAuthDisabledHttpError(err)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 error (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('put', url, data, config);
+                }
+                // Re-throw other errors
+                throw err;
+            }
+        },
+        async patch(url, data, config) {
+            try {
+                const response = await baseHttpClient.patch(url, data, config);
+                // Check for "Basic auth disabled" error in successful response
+                if (response.status === 401 && isBasicAuthDisabledError(response.body)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 response (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('patch', url, data, config);
+                }
+                return response;
+            }
+            catch (err) {
+                // Check if error is a 401 "Basic auth disabled" error
+                if (isBasicAuthDisabledHttpError(err)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 error (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('patch', url, data, config);
+                }
+                // Re-throw other errors
+                throw err;
+            }
+        },
+        async delete(url, config) {
+            try {
+                const response = await baseHttpClient.delete(url, config);
+                // Check for "Basic auth disabled" error in successful response
+                if (response.status === 401 && isBasicAuthDisabledError(response.body)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 response (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('delete', url, undefined, config);
+                }
+                return response;
+            }
+            catch (err) {
+                // Check if error is a 401 "Basic auth disabled" error
+                if (isBasicAuthDisabledHttpError(err)) {
+                    logger?.info('[OAuth Fallback] Intercepted 401 error (Basic auth disabled)', { url });
+                    return handleBasicAuthDisabled('delete', url, undefined, config);
+                }
+                // Re-throw other errors
+                throw err;
+            }
+        },
+    };
+}

package/dist/utils/resolveBaseUrl.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Factory that creates a resolver function bound to production and test base URLs.
+ *
+ * This removes duplication of base URL strings across capability files while keeping
+ * per-call decision logic explicit and testable.
+ *
+ * Usage:
+ *   const resolveBaseUrl = createResolveBaseUrl(prodUrl, testUrl);
+ *   const url = resolveBaseUrl(req.options); // returns test or prod based on useTestApi flag
+ *
+ * @param prodBaseUrl Production API base URL
+ * @param testBaseUrl Test/sandbox API base URL
+ * @returns A pure resolver function that accepts request options and returns the appropriate URL
+ */
+export declare function createResolveBaseUrl(prodBaseUrl: string, testBaseUrl: string): (opts?: {
+    useTestApi?: boolean;
+}) => string;
+/**
+ * Factory that creates a resolver function for OAuth2 token endpoints.
+ *
+ * MPL OAuth2 endpoints are separate from the main API:
+ * - Production: https://core.api.posta.hu/oauth2/token
+ * - Test/Sandbox: https://sandbox.api.posta.hu/oauth2/token
+ *
+ * Usage:
+ *   const resolveOAuthUrl = createResolveOAuthUrl(
+ *     'https://core.api.posta.hu/oauth2/token',
+ *     'https://sandbox.api.posta.hu/oauth2/token'
+ *   );
+ *   const url = resolveOAuthUrl(req.options); // returns test or prod endpoint
+ *
+ * @param prodOAuthUrl Production OAuth2 token endpoint
+ * @param testOAuthUrl Test/sandbox OAuth2 token endpoint
+ * @returns A pure resolver function that accepts request options and returns the appropriate OAuth URL
+ */
+export declare function createResolveOAuthUrl(prodOAuthUrl: string, testOAuthUrl: string): (opts?: {
+    useTestApi?: boolean;
+}) => string;
+/**
+ * Factory that creates a resolver function for tracking endpoints.
+ *
+ * MPL tracking endpoints are separate from the main API:
+ * - Production: https://core.api.posta.hu/nyomkovetes
+ * - Test/Sandbox: https://sandbox.api.posta.hu/nyomkovetes
+ *
+ * Usage:
+ *   const resolveTrackingUrl = createResolveTrackingUrl(
+ *     'https://core.api.posta.hu/nyomkovetes',
+ *     'https://sandbox.api.posta.hu/nyomkovetes'
+ *   );
+ *   const url = resolveTrackingUrl(req.options); // returns test or prod endpoint
+ *
+ * @param prodTrackingBaseUrl Production tracking API base URL
+ * @param testTrackingBaseUrl Test/sandbox tracking API base URL
+ * @returns A pure resolver function that accepts request options and returns the appropriate tracking URL
+ */
+export declare function createResolveTrackingUrl(prodTrackingBaseUrl: string, testTrackingBaseUrl: string): (opts?: {
+    useTestApi?: boolean;
+}) => string;
+/**
+ * Type definition for the resolver function returned by createResolveBaseUrl.
+ * Useful for typing capability function parameters.
+ */
+export type ResolveBaseUrl = ReturnType<typeof createResolveBaseUrl>;
+/**
+ * Type definition for the resolver function returned by createResolveOAuthUrl.
+ * Useful for typing capability function parameters.
+ */
+export type ResolveOAuthUrl = ReturnType<typeof createResolveOAuthUrl>;
+/**
+ * Type definition for the resolver function returned by createResolveTrackingUrl.
+ * Useful for typing capability function parameters.
+ */
+export type ResolveTrackingUrl = ReturnType<typeof createResolveTrackingUrl>;
+//# sourceMappingURL=resolveBaseUrl.d.ts.map