@shopickup/adapters-mpl 0.0.1

package/dist/capabilities/label.js

@@ -0,0 +1,328 @@
+/**
+ * MPL Adapter: Label Generation Capability
+ * Handles CREATE_LABEL and CREATE_LABELS operations
+ *
+ * Key differences from Foxpost:
+ * - Uses GET request instead of POST
+ * - Returns JSON array with base64-encoded label data
+ * - Multiple query parameters including labelType, labelFormat, orderBy, singleFile
+ * - Per-item error handling in the response array
+ */
+import { CarrierError, errorToLog, serializeForLog } from "@shopickup/core";
+import { safeValidateCreateLabelRequest, safeValidateCreateLabelsRequest } from '../validation.js';
+import { buildMPLHeaders } from '../utils/httpUtils.js';
+import { buildLabelQueryParams, serializeQueryParams } from '../mappers/label.js';
+import { randomUUID } from "node:crypto";
+const BLOB_FIELDS = new Set(['label', 'labelBase64']);
+function isSerializedBuffer(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        value.type === 'Buffer' &&
+        Array.isArray(value.data));
+}
+function summarizeBufferLike(value) {
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+        return {
+            omittedBinary: true,
+            byteLength: value.byteLength,
+            note: 'binary payload omitted from rawCarrierResponse',
+        };
+    }
+    return {
+        omittedBinary: true,
+        byteLength: value.data.length,
+        note: 'binary payload omitted from rawCarrierResponse',
+    };
+}
+function sanitizeRawValue(value, keyHint) {
+    if (typeof value === 'string') {
+        if (keyHint && BLOB_FIELDS.has(keyHint)) {
+            return `[truncated ${keyHint}; length=${value.length}]`;
+        }
+        return value;
+    }
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+        return summarizeBufferLike(value);
+    }
+    if (isSerializedBuffer(value)) {
+        return summarizeBufferLike(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeRawValue(item));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = sanitizeRawValue(nested, key);
+        }
+        return out;
+    }
+    return value;
+}
+function sanitizeRawCarrierResponse(raw) {
+    return sanitizeRawValue(raw);
+}
+/**
+ * Create a label (generate PDF) for a single parcel
+ * Delegates to createLabels to reuse batching logic
+ *
+ * Returns Promise<LabelResult> with file mapping and metadata
+ */
+export async function createLabel(req, ctx, resolveBaseUrl) {
+    // Validate single-label request using carrier-specific schema
+    const validated = safeValidateCreateLabelRequest(req);
+    if (!validated.success) {
+        throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: serializeForLog(validated.error) });
+    }
+    // Build batch request from validated single request
+    const batchReq = {
+        parcelCarrierIds: [validated.data.parcelCarrierId],
+        credentials: validated.data.credentials,
+        options: validated.data.options,
+    };
+    // Delegate to batch implementation
+    const response = await createLabels(batchReq, ctx, resolveBaseUrl);
+    // Extract first (only) result
+    if (!response || !Array.isArray(response.results)) {
+        throw new CarrierError("Unexpected response shape from createLabels", "Transient", { raw: serializeForLog(response) });
+    }
+    const results = response.results;
+    if (results.length === 0) {
+        throw new CarrierError("createLabels returned an empty results array", "Transient", { raw: serializeForLog(response) });
+    }
+    const result = results[0];
+    const file = result.fileId
+        ? response.files?.find((candidate) => candidate.id === result.fileId)
+        : undefined;
+    return {
+        ...result,
+        file,
+        rawCarrierResponse: response.rawCarrierResponse,
+    };
+}
+/**
+ * Create labels for multiple parcels in one call
+ *
+ * MPL GET /shipments/label endpoint:
+ * - Takes array of tracking numbers (query params)
+ * - Optional labelType, labelFormat, orderBy, singleFile params
+ * - Returns JSON array of LabelQueryResult objects with base64-encoded label data
+ * - Each result has trackingNumber, label (base64), errors/warnings arrays
+ *
+ * Returns structured response with files array and per-item results
+ */
+export async function createLabels(req, ctx, resolveBaseUrl) {
+    try {
+        // Validate the incoming request and use parsed data from Zod as the source of truth.
+        const validated = safeValidateCreateLabelsRequest({
+            parcelCarrierIds: req.parcelCarrierIds,
+            credentials: req.credentials,
+            options: req.options,
+        });
+        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");
+        }
+        if (!Array.isArray(validated.data.parcelCarrierIds) || validated.data.parcelCarrierIds.length === 0) {
+            return {
+                results: [],
+                files: [],
+                successCount: 0,
+                failureCount: 0,
+                totalCount: 0,
+                allSucceeded: false,
+                allFailed: false,
+                someFailed: false,
+                summary: "No parcels to process",
+            };
+        }
+        // Build query parameters and resolve base URL based on useTestApi
+        const queryParams = buildLabelQueryParams(validated.data);
+        const queryString = serializeQueryParams(queryParams);
+        const baseUrl = resolveBaseUrl({ useTestApi: validated.data.options.useTestApi });
+        const url = `${baseUrl}/shipments/label?${queryString}`;
+        ctx.logger?.debug("MPL: Creating labels batch", {
+            count: req.parcelCarrierIds.length,
+            labelType: queryParams.labelType,
+            labelFormat: queryParams.labelFormat,
+            orderBy: queryParams.orderBy,
+            singleFile: queryParams.singleFile,
+        });
+        try {
+            // Make request to MPL label API
+            // Response is JSON array of LabelQueryResult
+            const accountingCodeFromValidated = validated.data.options?.mpl?.accountingCode;
+            const httpResponse = await ctx.http.get(url, {
+                headers: buildMPLHeaders(validated.data.credentials, accountingCodeFromValidated),
+            });
+            const labelResults = httpResponse.body;
+            if (!Array.isArray(labelResults)) {
+                throw new CarrierError(`Invalid response: expected array, got ${typeof labelResults}`, "Transient", { raw: serializeForLog(labelResults) });
+            }
+            // Process results and build file resources
+            const fileMap = new Map();
+            const files = [];
+            const results = [];
+            let successCount = 0;
+            let failureCount = 0;
+            labelResults.forEach((result, idx) => {
+                const trackingNumber = result.trackingNumber || req.parcelCarrierIds[idx];
+                // Check if this result has errors
+                if (result.errors && result.errors.length > 0) {
+                    // Failed label
+                    failureCount++;
+                    results.push({
+                        inputId: trackingNumber,
+                        status: "failed",
+                        errors: result.errors.map(err => ({
+                            code: err.code,
+                            message: err.text || err.text_eng || "Unknown error",
+                        })),
+                        raw: { ...result, attemptedIndex: idx },
+                    });
+                }
+                else if (!result.label) {
+                    // No label data returned
+                    failureCount++;
+                    results.push({
+                        inputId: trackingNumber,
+                        status: "failed",
+                        errors: [{ code: "NO_LABEL_DATA", message: "No label data in response" }],
+                        raw: { ...result, attemptedIndex: idx },
+                    });
+                }
+                else {
+                    // Successful label - decode base64
+                    successCount++;
+                    const labelData = result.label;
+                    // Group labels by content (if singleFile=true, all will be same)
+                    // Use labelData as key to detect identical responses
+                    if (!fileMap.has(labelData)) {
+                        // First occurrence of this label payload: create a stable file resource.
+                        const buffer = Buffer.from(labelData, 'base64');
+                        const file = {
+                            id: randomUUID(),
+                            contentType: queryParams.labelFormat === 'ZPL' ? 'text/plain' : 'application/pdf',
+                            byteLength: buffer.byteLength,
+                            pages: 0,
+                            orientation: 'portrait',
+                            metadata: {
+                                labelType: queryParams.labelType,
+                                labelFormat: queryParams.labelFormat,
+                                isBase64Encoded: true,
+                            },
+                            // Attach raw bytes to the file so callers can access bytes directly
+                            rawBytes: buffer,
+                        };
+                        fileMap.set(labelData, { file, count: 0 });
+                        files.push(file);
+                    }
+                    const entry = fileMap.get(labelData);
+                    entry.count++;
+                    entry.file.pages = entry.count;
+                    entry.file.metadata = {
+                        ...(entry.file.metadata ?? {}),
+                        combinedLabels: entry.count > 1,
+                    };
+                    results.push({
+                        inputId: trackingNumber,
+                        status: "created",
+                        fileId: entry.file.id,
+                        pageRange: { start: entry.count, end: entry.count },
+                        raw: { trackingNumber, index: idx },
+                    });
+                }
+            });
+            ctx.logger?.info("MPL: Labels created", {
+                count: req.parcelCarrierIds.length,
+                successCount,
+                failureCount,
+                labelType: queryParams.labelType,
+                labelFormat: queryParams.labelFormat,
+                testMode: validated.data.options?.useTestApi ?? false,
+            });
+            return {
+                results,
+                files,
+                successCount,
+                failureCount,
+                totalCount: labelResults.length,
+                allSucceeded: failureCount === 0,
+                allFailed: successCount === 0,
+                someFailed: failureCount > 0 && successCount > 0,
+                summary: `${successCount} labels created, ${failureCount} failed`,
+                // Keep response metadata but truncate embedded label/blob payloads.
+                rawCarrierResponse: sanitizeRawCarrierResponse(serializeForLog(httpResponse)),
+            };
+        }
+        catch (labelError) {
+            // Handle HTTP errors
+            let errorMessage = `Failed to generate label: ${labelError?.message || "Unknown error"}`;
+            let errorCategory = 'Transient';
+            // If labelError is already a CarrierError, propagate it
+            if (labelError instanceof CarrierError) {
+                throw labelError;
+            }
+            // Try to extract HTTP status from error
+            const httpStatus = labelError?.response?.status;
+            if (httpStatus === 400) {
+                errorCategory = /not[_ -]?found/i.test(String(labelError?.response?.data?.error || labelError?.response?.data?.message || errorMessage))
+                    ? 'NotFound'
+                    : 'Validation';
+                errorMessage = errorCategory === 'NotFound' ? 'Requested tracking number not found' : "Invalid label request parameters";
+            }
+            else if (httpStatus === 401 || httpStatus === 403) {
+                errorCategory = 'Auth';
+                errorMessage = "Authentication failed - invalid credentials or authorization";
+            }
+            else if (httpStatus === 429) {
+                errorCategory = 'Transient';
+                errorMessage = "Rate limit exceeded";
+            }
+            else if (httpStatus && httpStatus >= 500) {
+                errorCategory = 'Transient';
+                errorMessage = "Server error - please retry";
+            }
+            else {
+                // Network or other error
+                errorCategory = 'Transient';
+            }
+            ctx.logger?.error("MPL: Label generation failed", {
+                count: req.parcelCarrierIds.length,
+                httpStatus,
+                error: errorToLog(labelError),
+            });
+            // Return failed results for all parcels
+            const results = req.parcelCarrierIds.map((trackingNumber) => ({
+                inputId: trackingNumber,
+                status: "failed",
+                errors: [{ code: "LABEL_GENERATION_FAILED", message: errorMessage }],
+                raw: { trackingNumber, error: serializeForLog(labelError) },
+            }));
+            return {
+                results,
+                files: [],
+                successCount: 0,
+                failureCount: results.length,
+                totalCount: results.length,
+                allSucceeded: false,
+                allFailed: true,
+                someFailed: false,
+                summary: `All ${results.length} labels failed`,
+                rawCarrierResponse: sanitizeRawCarrierResponse({ error: serializeForLog(labelError) }),
+            };
+        }
+    }
+    catch (error) {
+        if (error instanceof CarrierError) {
+            throw error;
+        }
+        ctx.logger?.error("MPL: Error creating labels", {
+            count: req.parcelCarrierIds.length,
+            error: errorToLog(error),
+        });
+        throw new CarrierError(`Label creation failed: ${error?.message || "Unknown error"}`, "Transient", { raw: serializeForLog(error) });
+    }
+}

package/dist/capabilities/parcels.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MPL Adapter: Parcel Creation Capability
+ *
+ * Handles CREATE_PARCEL and CREATE_PARCELS operations.
+ * Maps canonical Parcel objects to MPL ShipmentCreateRequest format
+ * and submits them via POST /shipments endpoint.
+ *
+ * Supports:
+ * - Single parcel creation (createParcel)
+ * - Batch creation up to 100 shipments (createParcels)
+ * - Partial failure handling (per-shipment results)
+ * - Label generation with configurable format
+ * - OAuth token exchange with fallback support
+ */
+import type { CreateParcelsResponse, CarrierResource, AdapterContext } from '@shopickup/core';
+import type { ResolveBaseUrl } from '../utils/resolveBaseUrl.js';
+import { type CreateParcelMPLRequest, type CreateParcelsMPLRequest } from '../validation.js';
+/**
+ * Create a single parcel in MPL
+ * Delegates to createParcels to reuse batching logic
+ */
+export declare function createParcel(req: CreateParcelMPLRequest, ctx: AdapterContext, createParcelsImpl: (req: CreateParcelsMPLRequest, ctx: AdapterContext) => Promise<CreateParcelsResponse>): Promise<CarrierResource>;
+/**
+ * Create multiple parcels in one call
+ *
+ * Maps canonical Parcel array to MPL ShipmentCreateRequest array.
+ * Supports up to 100 shipments per call (OpenAPI constraint).
+ * Returns per-item CarrierResource so callers can handle partial failures.
+ *
+ * @returns CreateParcelsResponse with summary and per-item results
+ */
+export declare function createParcels(req: CreateParcelsMPLRequest, ctx: AdapterContext, resolveBaseUrl: ResolveBaseUrl): Promise<CreateParcelsResponse>;
+//# sourceMappingURL=parcels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parcels.d.ts","sourceRoot":"","sources":["../../src/capabilities/parcels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAGV,qBAAqB,EACrB,eAAe,EAEf,cAAc,EAEf,MAAM,iBAAiB,CAAC;AAOzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAKL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAG7B,MAAM,kBAAkB,CAAC;AAoE1B;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,cAAc,EACnB,iBAAiB,EAAE,CACjB,GAAG,EAAE,uBAAuB,EAC5B,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,qBAAqB,CAAC,GAClC,OAAO,CAAC,eAAe,CAAC,CA4D1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,uBAAuB,EAC5B,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAiPhC"}

package/dist/capabilities/parcels.js

@@ -0,0 +1,284 @@
+/**
+ * MPL Adapter: Parcel Creation Capability
+ *
+ * Handles CREATE_PARCEL and CREATE_PARCELS operations.
+ * Maps canonical Parcel objects to MPL ShipmentCreateRequest format
+ * and submits them via POST /shipments endpoint.
+ *
+ * Supports:
+ * - Single parcel creation (createParcel)
+ * - Batch creation up to 100 shipments (createParcels)
+ * - Partial failure handling (per-shipment results)
+ * - Label generation with configurable format
+ * - OAuth token exchange with fallback support
+ */
+import { CarrierError, serializeForLog, errorToLog, } from '@shopickup/core';
+import { safeValidateCreateParcelRequest, safeValidateCreateParcelsRequest, safeValidateShipmentCreateRequest, safeValidateShipmentCreateResult, } from '../validation.js';
+import { mapParcelsToMPLShipments } from '../mappers/shipment.js';
+import { buildMPLHeaders } from '../utils/httpUtils.js';
+/**
+ * Translates MPL error to CarrierError with appropriate category
+ */
+function translateMPLShipmentError(error) {
+    if (error instanceof CarrierError) {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        const err = error;
+        // Check for HTTP response status
+        if (err.status) {
+            if (err.status === 400 || err.status === 404) {
+                return new CarrierError(`Validation error: ${err.message || 'Invalid request'}`, 'Validation', { raw: serializeForLog(err) });
+            }
+            else if (err.status === 401 || err.status === 403) {
+                return new CarrierError(`Authentication error: ${err.message || 'Unauthorized'}`, 'Auth', { raw: serializeForLog(err) });
+            }
+            else if (err.status === 429) {
+                return new CarrierError(`Rate limit exceeded: ${err.message || 'Too many requests'}`, 'RateLimit', { raw: serializeForLog(err) });
+            }
+            else if (err.status >= 500) {
+                return new CarrierError(`Server error: ${err.message || 'Internal server error'}`, 'Transient', { raw: serializeForLog(err) });
+            }
+        }
+        // Check for MPL-specific error structure
+        if (err.fault?.faultstring) {
+            return new CarrierError(`MPL error: ${err.fault.faultstring}`, 'Transient', { raw: serializeForLog(err) });
+        }
+        return new CarrierError(`Shipment creation error: ${err.message || 'Unknown error'}`, 'Transient', { raw: serializeForLog(err) });
+    }
+    return new CarrierError(`Shipment creation error: ${String(error)}`, 'Transient');
+}
+/**
+ * Create a single parcel in MPL
+ * Delegates to createParcels to reuse batching logic
+ */
+export async function createParcel(req, ctx, createParcelsImpl) {
+    const validated = safeValidateCreateParcelRequest(req);
+    if (!validated.success) {
+        throw new CarrierError(`Invalid request: ${validated.error.message}`, 'Validation', { raw: serializeForLog(validated.error.issues) });
+    }
+    const parsedReq = validated.data;
+    const batchReq = {
+        parcels: [parsedReq.parcel],
+        credentials: parsedReq.credentials,
+        options: parsedReq.options,
+    };
+    const response = await createParcelsImpl(batchReq, ctx);
+    // Validate response shape
+    if (!response || !Array.isArray(response.results)) {
+        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, attach full response for context
+    const result = results[0];
+    if (result.status === 'failed') {
+        const firstError = result.errors?.[0]?.message;
+        throw new CarrierError(firstError
+            ? `Parcel creation failed: ${firstError}`
+            : 'Parcel creation failed', 'Validation', {
+            raw: serializeForLog({
+                result,
+                rawCarrierResponse: response.rawCarrierResponse,
+            }),
+        });
+    }
+    return {
+        ...result,
+        rawCarrierResponse: response.rawCarrierResponse,
+    };
+}
+/**
+ * Create multiple parcels in one call
+ *
+ * Maps canonical Parcel array to MPL ShipmentCreateRequest array.
+ * Supports up to 100 shipments per call (OpenAPI constraint).
+ * 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 {
+        const validated = safeValidateCreateParcelsRequest(req);
+        if (!validated.success) {
+            throw new CarrierError(`Invalid request: ${validated.error.message}`, 'Validation', { raw: serializeForLog(validated.error.issues) });
+        }
+        const parsedReq = validated.data;
+        const internalOptions = {
+            useTestApi: parsedReq.options.useTestApi ?? false,
+            labelType: parsedReq.options.mpl.labelType,
+            accountingCode: parsedReq.options.mpl.accountingCode,
+            agreementCode: parsedReq.options.mpl.agreementCode,
+            bankAccountNumber: parsedReq.options.mpl.bankAccountNumber,
+        };
+        // Validate we have required context
+        if (!ctx.http) {
+            throw new CarrierError('HTTP client not provided in context', 'Permanent');
+        }
+        if (!Array.isArray(parsedReq.parcels) || parsedReq.parcels.length === 0) {
+            return {
+                results: [],
+                successCount: 0,
+                failureCount: 0,
+                totalCount: 0,
+                allSucceeded: false,
+                allFailed: false,
+                someFailed: false,
+                summary: 'No parcels to process',
+            };
+        }
+        // Enforce batch size limit (OpenAPI: max 100 shipments per call)
+        if (parsedReq.parcels.length > 100) {
+            throw new CarrierError(`Too many parcels: ${parsedReq.parcels.length} > 100 (MPL API limit)`, 'Validation', { raw: { maxAllowed: 100, requested: parsedReq.parcels.length } });
+        }
+        const baseUrl = resolveBaseUrl({ useTestApi: internalOptions.useTestApi });
+        const useTestApi = internalOptions.useTestApi;
+        ctx.logger?.debug('MPL: Creating parcels batch', {
+            count: parsedReq.parcels.length,
+            testMode: useTestApi,
+        });
+        // Extract sender information from first parcel (assumes uniform sender across batch)
+        const firstParcel = parsedReq.parcels[0];
+        if (!firstParcel.shipper) {
+            throw new CarrierError('Missing shipper information in parcel', 'Validation');
+        }
+        // Map canonical parcels to MPL shipments
+        const mplShipments = mapParcelsToMPLShipments(parsedReq.parcels, firstParcel.shipper, internalOptions.agreementCode, internalOptions.bankAccountNumber, internalOptions.labelType);
+        ctx.logger?.debug('MPL: Mapped parcels to MPL shipments', {
+            shipments: serializeForLog(mplShipments),
+        });
+        // Validate each mapped shipment
+        const mplShipmentsWithValidation = mplShipments.map((shipment, idx) => {
+            const validation = safeValidateShipmentCreateRequest(shipment);
+            if (!validation.success) {
+                ctx.logger?.warn('MPL: Shipment validation failed', {
+                    shipmentIdx: idx,
+                    errors: serializeForLog(validation.error.issues),
+                });
+                // Continue anyway - be lenient
+            }
+            return shipment;
+        });
+        // Call MPL API
+        const httpResponse = await ctx.http.post(`${baseUrl}/shipments`, mplShipmentsWithValidation, {
+            headers: buildMPLHeaders(parsedReq.credentials, internalOptions.accountingCode),
+        });
+        // Extract and validate response body
+        const carrierRespBody = httpResponse.body;
+        if (!Array.isArray(carrierRespBody)) {
+            throw new CarrierError('Invalid response from MPL: expected array', 'Transient', { raw: serializeForLog(carrierRespBody) });
+        }
+        // Process each result
+        const results = carrierRespBody.map((result, idx) => {
+            // Validate result shape
+            const resultValidation = safeValidateShipmentCreateResult(result);
+            if (!resultValidation.success) {
+                ctx.logger?.warn('MPL: Result validation failed', {
+                    resultIdx: idx,
+                    errors: serializeForLog(resultValidation.error.issues),
+                });
+            }
+            // Check for errors in result
+            if (result.errors && Array.isArray(result.errors) && result.errors.length > 0) {
+                const errors = result.errors.map((err) => ({
+                    field: err.parameter || 'unknown',
+                    code: err.code || 'UNKNOWN_ERROR',
+                    message: `${err.text || err.text_eng || 'Unknown error'}`,
+                }));
+                ctx.logger?.warn('MPL: Shipment errors', {
+                    shipmentIdx: idx,
+                    webshopId: result.webshopId,
+                    errorCount: errors.length,
+                    errorSummary: errors.map(e => `${e.field}: ${e.code}`),
+                    errors: serializeForLog(errors),
+                });
+                const failedResource = {
+                    carrierId: undefined,
+                    status: 'failed',
+                    raw: serializeForLog(result),
+                    errors,
+                };
+                return failedResource;
+            }
+            // Check for tracking number (indicates success)
+            if (!result.trackingNumber) {
+                ctx.logger?.warn('MPL: No tracking number in result', {
+                    shipmentIdx: idx,
+                    webshopId: result.webshopId,
+                });
+                const failedResource = {
+                    carrierId: undefined,
+                    status: 'failed',
+                    raw: serializeForLog(result),
+                    errors: [
+                        {
+                            field: 'trackingNumber',
+                            code: 'NO_TRACKING_NUMBER',
+                            message: 'No tracking number assigned by carrier',
+                        },
+                    ],
+                };
+                return failedResource;
+            }
+            // Success - shipment created with tracking number
+            const successResource = {
+                carrierId: result.trackingNumber,
+                status: 'created',
+                raw: serializeForLog(result),
+            };
+            ctx.logger?.debug('MPL: Shipment created', {
+                shipmentIdx: idx,
+                trackingNumber: result.trackingNumber,
+                webshopId: result.webshopId,
+            });
+            return successResource;
+        });
+        // 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('MPL: Parcels creation finished', {
+            count: totalCount,
+            testMode: useTestApi,
+            summary,
+            successCount,
+            failureCount,
+        });
+        // Return strongly-typed response with a sanitized carrier response for debugging
+        // Avoid serializing the whole httpResponse (which may contain streams/buffers)
+        // — include only the most useful parts: status, headers, body
+        return {
+            results,
+            successCount,
+            failureCount,
+            totalCount,
+            allSucceeded: failureCount === 0 && totalCount > 0,
+            allFailed: successCount === 0 && totalCount > 0,
+            someFailed: successCount > 0 && failureCount > 0,
+            summary,
+            rawCarrierResponse: serializeForLog({ status: httpResponse.status, headers: httpResponse.headers, body: httpResponse.body }),
+        };
+    }
+    catch (error) {
+        ctx.logger?.error('MPL: Error creating parcels batch', {
+            error: errorToLog(error),
+        });
+        if (error instanceof CarrierError) {
+            throw error;
+        }
+        throw translateMPLShipmentError(error);
+    }
+}