@shopickup/adapters-foxpost 0.0.1

package/README.md

@@ -0,0 +1,48 @@
+# @shopickup/adapters-foxpost
+
+Foxpost adapter for Shopickup.
+
+[GitHub repo](https://github.com/shopickup/shopickup-integration-layer)
+[Issues](https://github.com/shopickup/shopickup-integration-layer/issues)
+
+## What it does
+
+- `CREATE_PARCEL`
+- `CREATE_LABEL`
+- `TRACK`
+- `LIST_PICKUP_POINTS`
+
+## Install
+
+```bash
+pnpm add @shopickup/adapters-foxpost @shopickup/core
+```
+
+## Quick start
+
+```ts
+import { FoxpostAdapter } from '@shopickup/adapters-foxpost';
+import { executeCreateLabelFlow } from '@shopickup/core';
+
+const adapter = new FoxpostAdapter('https://webapi.foxpost.hu');
+
+const result = await executeCreateLabelFlow({
+  adapter,
+  shipment: {
+    id: 'order-001',
+    sender: { name: 'Shop', street: 'Main', city: 'Budapest', postalCode: '1011', country: 'HU' },
+    recipient: { name: 'Customer', street: 'Fo utca 2', city: 'Siofok', postalCode: '8600', country: 'HU' },
+    service: 'standard',
+    totalWeight: 1200,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  },
+  parcels: [{ id: 'parcel-1', weight: 1200 }],
+  credentials: { apiKey: 'your-foxpost-api-key' },
+  context: { http: yourHttpClient, logger: console },
+});
+```
+
+## Status
+
+Published as `0.x.x` while the adapter API is still evolving.

package/dist/capabilities/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Foxpost Adapter: Capabilities Export
+ * Re-exports all capability methods for clean imports
+ */
+export { createParcel, createParcels } from './parcels.js';
+export { createLabel, createLabels } from './label.js';
+export { track } from './track.js';
+export { fetchPickupPoints } from './pickup-points.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/capabilities/index.js

@@ -0,0 +1,8 @@
+/**
+ * Foxpost Adapter: Capabilities Export
+ * Re-exports all capability methods for clean imports
+ */
+export { createParcel, createParcels } from './parcels.js';
+export { createLabel, createLabels } from './label.js';
+export { track } from './track.js';
+export { fetchPickupPoints } from './pickup-points.js';

package/dist/capabilities/label.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Foxpost Adapter: Label Generation Capability
+ * Handles CREATE_LABEL and CREATE_LABELS operations
+ */
+import type { AdapterContext, CreateLabelResponse, CreateLabelsResponse } from "@shopickup/core";
+import type { CreateLabelRequestFoxpost, CreateLabelsRequestFoxpost } from "../validation.js";
+import type { ResolveBaseUrl } from "../utils/resolveBaseUrl.js";
+/**
+ * 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 declare function createLabel(req: CreateLabelRequestFoxpost, ctx: AdapterContext, resolveBaseUrl: ResolveBaseUrl): Promise<CreateLabelResponse>;
+/**
+ * Create labels for multiple parcels in one call
+ *
+ * Foxpost POST /api/label/{pageSize} endpoint:
+ * - Takes array of parcel IDs (barcodes)
+ * - Returns PDF with all labels (optionally concatenated based on pageSize)
+ * - For A7 size on A4 page, supports startPos parameter (1-7)
+ *
+ * Returns structured response with files array and per-item results
+ * Foxpost returns one PDF (combined), so all results reference the same file
+ */
+export declare function createLabels(req: CreateLabelsRequestFoxpost, ctx: AdapterContext, resolveBaseUrl: ResolveBaseUrl): Promise<CreateLabelsResponse>;
+//# sourceMappingURL=label.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../src/capabilities/label.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAET,cAAc,EACf,mBAAmB,EAClB,oBAAoB,EAGtB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAC3B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAkEjE;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,yBAAyB,EAC9B,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAkD9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,0BAA0B,EAC/B,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAqS/B"}

package/dist/capabilities/label.js

@@ -0,0 +1,370 @@
+/**
+ * Foxpost Adapter: Label Generation Capability
+ * Handles CREATE_LABEL and CREATE_LABELS operations
+ */
+import { CarrierError, errorToLog, serializeForLog } from "@shopickup/core";
+import { translateFoxpostError } from '../errors.js';
+import { safeValidateCreateLabelRequest, safeValidateCreateLabelsRequest, safeValidateFoxpostLabelPdfRaw, safeValidateFoxpostApiError, } from "../validation.js";
+import { buildFoxpostBinaryHeaders } from '../utils/httpUtils.js';
+import { URLSearchParams } from "node:url";
+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 request format and credentials
+    const validated = safeValidateCreateLabelRequest(req);
+    if (!validated.success) {
+        throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: serializeForLog(validated.error) });
+    }
+    // Convert single label request to batch request
+    const batchReq = {
+        parcelCarrierIds: [validated.data.parcelCarrierId],
+        credentials: req.credentials,
+        options: req.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) });
+    }
+    // Return the first (only) label result
+    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
+ *
+ * Foxpost POST /api/label/{pageSize} endpoint:
+ * - Takes array of parcel IDs (barcodes)
+ * - Returns PDF with all labels (optionally concatenated based on pageSize)
+ * - For A7 size on A4 page, supports startPos parameter (1-7)
+ *
+ * Returns structured response with files array and per-item results
+ * Foxpost returns one PDF (combined), so all results reference the same file
+ */
+export async function createLabels(req, ctx, resolveBaseUrl) {
+    try {
+        // Validate request format and credentials
+        const validated = safeValidateCreateLabelsRequest(req);
+        if (!validated.success) {
+            throw new CarrierError(`Invalid request: ${validated.error.message}`, "Validation", { raw: validated.error });
+        }
+        if (!ctx.http) {
+            throw new CarrierError("HTTP client not provided in context", "Permanent");
+        }
+        if (!Array.isArray(req.parcelCarrierIds) || req.parcelCarrierIds.length === 0) {
+            return {
+                results: [],
+                files: [],
+                successCount: 0,
+                failureCount: 0,
+                totalCount: 0,
+                allSucceeded: false,
+                allFailed: false,
+                someFailed: false,
+                summary: "No parcels to process",
+            };
+        }
+        // Normalize public request options to adapter internal options.
+        const internalOptions = {
+            useTestApi: validated.data.options?.useTestApi ?? false,
+            size: validated.data.options?.size ?? "A7",
+            startPos: validated.data.options?.foxpost?.startPos,
+            isPortrait: validated.data.options?.foxpost?.isPortrait ?? false,
+        };
+        const baseUrl = resolveBaseUrl({ useTestApi: internalOptions.useTestApi });
+        // Construct URL with page size and optional params
+        const params = new URLSearchParams();
+        if (internalOptions.startPos !== undefined && internalOptions.startPos !== null) {
+            params.set('startPos', String(internalOptions.startPos));
+        }
+        if (internalOptions.isPortrait !== undefined && internalOptions.isPortrait !== null) {
+            params.set('isPortrait', String(internalOptions.isPortrait));
+        }
+        const url = `${baseUrl}/api/label/${internalOptions.size}${params.toString() ? `?${params.toString()}` : ''}`;
+        ctx.logger?.debug("Foxpost: Creating labels batch", {
+            testMode: internalOptions.useTestApi,
+            count: req.parcelCarrierIds.length,
+            size: internalOptions.size,
+            startPos: internalOptions.startPos,
+            isPortrait: internalOptions.isPortrait,
+        });
+        try {
+            // Make request to Foxpost label API
+            // Response is PDF binary data
+            const httpResponse = await ctx.http.post(url, validated.data.parcelCarrierIds, {
+                headers: buildFoxpostBinaryHeaders(validated.data.credentials),
+                responseType: "arraybuffer",
+            });
+            // Extract buffer from normalized HttpResponse
+            const pdfBuffer = httpResponse.body;
+            // Validate PDF binary response is non-empty
+            const pdfValidation = safeValidateFoxpostLabelPdfRaw(pdfBuffer);
+            if (!pdfValidation.success) {
+                throw new CarrierError(`Invalid PDF response: ${pdfValidation.error.message}`, "Transient", { raw: serializeForLog(pdfValidation.error) });
+            }
+            // Get byte length (works for Buffer and Uint8Array)
+            const byteLength = pdfBuffer instanceof Buffer ? pdfBuffer.byteLength :
+                pdfBuffer instanceof Uint8Array ? pdfBuffer.byteLength :
+                    0;
+            // Create file resource for the single PDF
+            const fileId = randomUUID();
+            const file = {
+                id: fileId,
+                contentType: "application/pdf",
+                byteLength,
+                pages: req.parcelCarrierIds.length, // One page per label (Foxpost behavior)
+                orientation: internalOptions.isPortrait === false ? 'landscape' : 'portrait',
+                metadata: {
+                    size: internalOptions.size,
+                    isPortrait: internalOptions.isPortrait,
+                    barcodeCount: req.parcelCarrierIds.length,
+                    combined: true, // All labels in one file
+                },
+                // Attach raw bytes so dev-server responses can include file bytes directly
+                rawBytes: pdfBuffer,
+            };
+            ctx.logger?.info("Foxpost: Labels created successfully", {
+                count: req.parcelCarrierIds.length,
+                size: internalOptions.size,
+                testMode: internalOptions.useTestApi,
+            });
+            // Create per-item results, all referencing the same file
+            const results = req.parcelCarrierIds.map((barcode, idx) => ({
+                inputId: barcode,
+                status: "created",
+                fileId,
+                pageRange: { start: idx + 1, end: idx + 1 }, // One page per label
+                raw: {
+                    barcode,
+                    format: "PDF",
+                    pageSize: internalOptions.size,
+                    startPos: internalOptions.startPos,
+                    pageNumber: idx + 1,
+                },
+            }));
+            return {
+                results,
+                files: [file],
+                successCount: results.length,
+                failureCount: 0,
+                totalCount: results.length,
+                allSucceeded: true,
+                allFailed: false,
+                someFailed: false,
+                summary: `All ${results.length} labels generated successfully`,
+                // Preserve status/headers but strip embedded label/blob payloads.
+                rawCarrierResponse: sanitizeRawCarrierResponse(serializeForLog(httpResponse)),
+            };
+        }
+        catch (labelError) {
+            // Try to parse error response as Foxpost ApiError
+            let errorMessage = `Failed to generate label: ${labelError?.message || "Unknown error"}`;
+            let errorCategory = 'Transient';
+            // If labelError is from Foxpost API and contains status/error info, extract it
+            if (labelError instanceof CarrierError) {
+                // Already a CarrierError from validation, propagate it
+                throw labelError;
+            }
+            // Try to extract HTTP status from axios-like error
+            const httpStatus = labelError?.response?.status;
+            ctx.logger?.debug("Foxpost error analysis", {
+                hasResponse: !!labelError?.response,
+                httpStatus,
+                dataType: labelError?.response?.data?.constructor?.name,
+                isBuffer: Buffer.isBuffer(labelError?.response?.data),
+            });
+            if (httpStatus) {
+                // Attempt to parse error body as JSON if available
+                try {
+                    let errorBody = labelError?.response?.data;
+                    if (errorBody) {
+                        ctx.logger?.debug("Raw error body before parsing", {
+                            type: errorBody?.constructor?.name,
+                            isBuffer: Buffer.isBuffer(errorBody),
+                            isUint8Array: errorBody instanceof Uint8Array,
+                            byteLength: errorBody?.length || errorBody?.byteLength,
+                        });
+                        // If error body is a Buffer, decode it to string first
+                        if (Buffer.isBuffer(errorBody)) {
+                            const decoded = errorBody.toString('utf-8');
+                            ctx.logger?.debug("Decoded buffer to string", { decoded });
+                            errorBody = JSON.parse(decoded);
+                        }
+                        else if (errorBody instanceof Uint8Array) {
+                            errorBody = JSON.parse(new TextDecoder().decode(errorBody));
+                        }
+                        ctx.logger?.debug("Parsed error body", { errorBody });
+                        // Try to parse as Foxpost ApiError
+                        const apiErrorValidation = safeValidateFoxpostApiError(errorBody);
+                        if (apiErrorValidation.success) {
+                            const apiError = apiErrorValidation.data;
+                            // Use error code as message if available
+                            if (apiError.error) {
+                                errorMessage = apiError.error;
+                                ctx.logger?.debug("Extracted error message from API response", { message: errorMessage });
+                            }
+                            // Map HTTP status to error category
+                            if (httpStatus === 400) {
+                                errorCategory = /not[_ -]?found/i.test(String(apiError.error || errorMessage))
+                                    ? 'NotFound'
+                                    : 'Validation';
+                            }
+                            else if (httpStatus === 401 || httpStatus === 403) {
+                                errorCategory = 'Auth';
+                            }
+                            else if (httpStatus >= 500) {
+                                errorCategory = 'Transient';
+                            }
+                        }
+                        else {
+                            // Validation failed, log the issue
+                            ctx.logger?.debug("Failed to validate Foxpost API error response", {
+                                validation: apiErrorValidation.error,
+                                attemptedBody: errorBody,
+                            });
+                        }
+                    }
+                }
+                catch (parseError) {
+                    // If parsing fails, log and use default error category based on status
+                    ctx.logger?.debug("Failed to parse error body", {
+                        error: parseError?.message,
+                    });
+                    if (httpStatus === 400) {
+                        errorCategory = 'Validation';
+                    }
+                    else if (httpStatus === 401 || httpStatus === 403) {
+                        errorCategory = 'Auth';
+                    }
+                    else if (httpStatus >= 500) {
+                        errorCategory = 'Transient';
+                    }
+                }
+            }
+            // If PDF generation fails, return error results for all barcodes
+            ctx.logger?.error("Foxpost: Label generation failed", {
+                count: req.parcelCarrierIds.length,
+                size: internalOptions.size,
+                error: errorToLog(labelError),
+            });
+            // Return failed results for all parcels
+            const errorObj = {
+                code: "LABEL_GENERATION_FAILED",
+                message: errorMessage,
+            };
+            ctx.logger?.debug("Creating error object", {
+                code: errorObj.code,
+                message: errorObj.message,
+                stringified: JSON.stringify(errorObj),
+            });
+            const results = req.parcelCarrierIds.map((barcode) => {
+                const result = {
+                    inputId: barcode,
+                    status: "failed",
+                    errors: [errorObj],
+                    raw: { barcode, error: serializeForLog(labelError) },
+                };
+                ctx.logger?.debug("Result object created", {
+                    inputId: result.inputId,
+                    status: result.status,
+                    errorsLength: result.errors?.length,
+                    firstError: result.errors?.[0],
+                });
+                return result;
+            });
+            ctx.logger?.debug("Error results being returned", {
+                sample: results[0],
+                errorMessage,
+                errorCategory,
+            });
+            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("Foxpost: Error creating labels", {
+            count: req.parcelCarrierIds.length,
+            error: errorToLog(error),
+        });
+        throw translateFoxpostError(error);
+    }
+}

package/dist/capabilities/parcels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Foxpost Adapter: Parcel Creation Capabilities
+ * Handles CREATE_PARCEL and CREATE_PARCELS operations
+ */
+import type { CarrierResource, AdapterContext, CreateParcelRequest, CreateParcelsRequest, CreateParcelsResponse } from "@shopickup/core";
+import type { ResolveBaseUrl } from '../utils/resolveBaseUrl.js';
+/**
+ * Create a single parcel in Foxpost
+ * Delegates to createParcels to reuse batching logic
+ */
+export declare function createParcel(req: CreateParcelRequest, ctx: AdapterContext, createParcelsImpl: (req: CreateParcelsRequest, ctx: AdapterContext) => Promise<CreateParcelsResponse>): Promise<CarrierResource>;
+/**
+ * Create multiple parcels in one call
+ * Maps canonical Parcel array to Foxpost CreateParcelRequest and calls the
+ * Foxpost batch endpoint which accepts an array. Returns per-item CarrierResource
+ * so callers can handle partial failures.
+ *
+ * @returns CreateParcelsResponse with summary and per-item results
+ */
+export declare function createParcels(req: CreateParcelsRequest, 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;;;GAGG;AAEH,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,cAAc,EACnB,iBAAiB,EAAE,CAAC,GAAG,EAAE,oBAAoB,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,qBAAqB,CAAC,GACpG,OAAO,CAAC,eAAe,CAAC,CA2C1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,oBAAoB,EACzB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAmOhC"}