@shopickup/adapters-foxpost 0.0.1

package/dist/validation.js

@@ -0,0 +1,799 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for runtime validation
+ */
+/**
+ * Money schema (ISO currency amount in smallest unit)
+ */
+const MoneySchema = z.object({
+    amount: z.number().int().nonnegative().describe('Amount must be non-negative'),
+    currency: z.string().length(3).describe('Currency must be ISO 4217 code (3 chars)'),
+});
+/**
+ * Contact schema (phone/email optional)
+ */
+const ContactSchema = z.object({
+    name: z.string().min(1).describe('Name is required'),
+    phone: z.string().optional(),
+    email: z.string().optional(),
+    company: z.string().optional(),
+});
+/**
+ * Address schema (full shipping address)
+ */
+const AddressSchema = z.object({
+    name: z.string().min(1).describe('Address name is required'),
+    street: z.string().min(1).describe('Street is required'),
+    city: z.string().min(1).describe('City is required'),
+    postalCode: z.string().min(1).describe('Postal code is required'),
+    country: z.string().min(1).describe('Country is required'),
+    phone: z.string().optional(),
+    email: z.email().optional(),
+    company: z.string().optional(),
+    province: z.string().optional(),
+    isPoBox: z.boolean().optional(),
+});
+/**
+ * Home delivery schema
+ */
+const HomeDeliverySchema = z.object({
+    method: z.literal('HOME'),
+    address: AddressSchema,
+    instructions: z.string().optional(),
+});
+/**
+ * Pickup point delivery schema
+ */
+const PickupPointDeliverySchema = z.object({
+    method: z.literal('PICKUP_POINT'),
+    pickupPoint: z.object({
+        id: z.string().min(1, 'Pickup point ID is required'),
+        provider: z.string().optional(),
+        name: z.string().optional(),
+        address: AddressSchema.optional(),
+        type: z.enum(['LOCKER', 'SHOP', 'POST_OFFICE', 'OTHER']).optional(),
+    }),
+    instructions: z.string().optional(),
+});
+/**
+ * Delivery discriminated union
+ */
+const DeliverySchema = z.discriminatedUnion('method', [
+    HomeDeliverySchema,
+    PickupPointDeliverySchema,
+]);
+/**
+ * Parcel schema (canonical domain type)
+ */
+const ParcelSchema = z.object({
+    id: z.string().min(1),
+    shipper: z.object({
+        contact: ContactSchema,
+        address: AddressSchema,
+    }),
+    recipient: z.object({
+        contact: ContactSchema,
+        delivery: DeliverySchema,
+    }),
+    carrierIds: z.record(z.string(), z.string()).optional(),
+    service: z.enum(['standard', 'express', 'economy', 'overnight']),
+    carrierServiceCode: z.string().optional(),
+    package: z.object({
+        weightGrams: z.number().gt(0),
+        dimensionsCm: z.object({
+            length: z.number().gt(0),
+            width: z.number().gt(0),
+            height: z.number().gt(0),
+        }).optional(),
+    }),
+    handling: z.object({
+        fragile: z.boolean().optional(),
+        perishables: z.boolean().optional(),
+        batteries: z.enum(['NONE', 'LITHIUM_ION', 'LITHIUM_METAL']).optional(),
+    }).optional(),
+    cod: z.object({
+        amount: MoneySchema,
+        reference: z.string().optional(),
+    }).optional(),
+    declaredValue: MoneySchema.optional(),
+    insurance: z.object({
+        amount: MoneySchema,
+    }).optional(),
+    references: z.object({
+        orderId: z.string().optional(),
+        customerReference: z.string().optional(),
+    }).optional(),
+    items: z.array(z.object({
+        sku: z.string().optional(),
+        quantity: z.number().gt(0),
+        description: z.string().optional(),
+        weight: z.number().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+    })).optional(),
+    status: z.enum(['draft', 'created', 'closed', 'label_generated', 'shipped', 'delivered', 'exception']).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+}).strict();
+/**
+ * Foxpost package size schema (used in both HD and APM)
+ */
+const FoxpostPackageSizeSchema = z.enum(['XS', 'S', 'M', 'L', 'XL', '1', '2', '3', '4', '5']);
+/**
+ * Hungarian phone number schema (mobile only, +36 or 36 prefix)
+ */
+const HungarianPhoneSchema = z.string().regex(/^(\+36|36)(20|30|31|70|50|51)\d{7}$/, 'Phone must be Hungarian mobile');
+/**
+ * Credentials schema - requires apiKey, basicUsername, and basicPassword all together
+ */
+const FoxpostCredentialsSchema = z.object({
+    apiKey: z.string().min(1, 'API key is required'),
+    basicUsername: z.string().min(1, 'Basic auth username is required'),
+    basicPassword: z.string().min(1, 'Basic auth password is required'),
+}).strict();
+/**
+ * Home Delivery parcel schema with discriminator
+ */
+const FoxpostParcelHDSchema = z.object({
+    type: z.literal('HD'),
+    cod: z.number().int().min(0).max(1000000).optional().default(0),
+    comment: z.string().max(50).optional(),
+    deliveryNote: z.string().optional(),
+    fragile: z.boolean().optional().default(false),
+    label: z.boolean().optional(),
+    recipientAddress: z.string().min(1).max(150),
+    recipientCity: z.string().min(1).max(50),
+    recipientCountry: z.string().optional(),
+    recipientEmail: z.email(),
+    recipientName: z.string().min(1).max(150),
+    recipientPhone: HungarianPhoneSchema,
+    recipientZip: z.string().min(1).max(4),
+    refCode: z.string().max(30).optional(),
+    size: FoxpostPackageSizeSchema,
+}).strict();
+/**
+ * APM (Automated Parcel Machine) parcel schema with discriminator
+ */
+const FoxpostParcelAPMSchema = z.object({
+    type: z.literal('APM'),
+    cod: z.number().int().min(0).max(1000000).optional().default(0),
+    comment: z.string().max(50).optional(),
+    destination: z.string().min(1),
+    label: z.boolean().optional(),
+    recipientEmail: z.email(),
+    recipientName: z.string().min(1).max(150),
+    recipientPhone: HungarianPhoneSchema,
+    refCode: z.string().max(30).optional(),
+    size: FoxpostPackageSizeSchema,
+    uniqueBarcode: z.string().min(4).max(20).regex(/^(?=.*[a-zA-Z].*[a-zA-Z].*[a-zA-Z].*[a-zA-Z])(?=.*\d.*\d.*\d.*\d)/).optional(),
+}).strict();
+/**
+ * Discriminated union of HD and APM parcel types
+ */
+export const FoxpostParcelSchema = z.discriminatedUnion('type', [
+    FoxpostParcelHDSchema,
+    FoxpostParcelAPMSchema
+]);
+/**
+ * CreateParcelRequest Zod schema
+ */
+export const CreateParcelRequestFoxpostSchema = z.object({
+    parcel: ParcelSchema,
+    credentials: FoxpostCredentialsSchema,
+    options: z.object({
+        useTestApi: z.boolean().optional()
+    }).optional()
+});
+export const CreateParcelsRequestFoxpostSchema = z.object({
+    parcels: z.array(ParcelSchema).min(1),
+    credentials: FoxpostCredentialsSchema,
+    options: z.object({
+        useTestApi: z.boolean().optional()
+    }).optional()
+});
+export const CreateLabelRequestFoxpostSchema = z.object({
+    parcelCarrierId: z.string().min(1, 'Parcel carrier ID is required'),
+    credentials: FoxpostCredentialsSchema,
+    options: z.object({
+        useTestApi: z.boolean().optional(),
+        size: z.enum(['A6', 'A7', '_85X85']).default('A7'),
+        foxpost: z.object({
+            startPos: z.number().int().min(0).max(7).optional(),
+            isPortrait: z.boolean().optional().default(false),
+        }).optional(),
+    }).optional()
+});
+/**
+ * Batch label request schema
+ * Similar to CreateParcelsRequest but for labels
+ */
+export const CreateLabelsRequestFoxpostSchema = z.object({
+    parcelCarrierIds: z.array(z.string().min(1)).min(1, 'At least one parcel ID is required'),
+    credentials: FoxpostCredentialsSchema,
+    options: z.object({
+        useTestApi: z.boolean().optional(),
+        size: z.enum(['A6', 'A7', '_85X85']).default('A7'),
+        foxpost: z.object({
+            startPos: z.number().int().min(0).max(7).optional(),
+            isPortrait: z.boolean().optional().default(false),
+        }).optional(),
+    }).optional()
+});
+/**
+ * TrackingRequest Zod schema
+ */
+export const TrackingRequestFoxpostSchema = z.object({
+    trackingNumber: z.string().min(1, 'Tracking number is required'),
+    credentials: FoxpostCredentialsSchema,
+    options: z.object({
+        useTestApi: z.boolean().optional()
+    }).optional()
+});
+/**
+ * Helper to validate and extract credentials from a request
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostCredentials(credentials) {
+    return FoxpostCredentialsSchema.parse(credentials);
+}
+/**
+ * Helper to safely validate credentials without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostCredentials(credentials) {
+    return FoxpostCredentialsSchema.safeParse(credentials);
+}
+/**
+ * Helper to validate a CreateParcelRequest
+ * Returns parsed and validated request or throws ZodError
+ */
+export function validateCreateParcelRequest(req) {
+    return CreateParcelRequestFoxpostSchema.parse(req);
+}
+/**
+ * Helper to validate a CreateParcelsRequest
+ * Returns parsed and validated request or throws ZodError
+ */
+export function validateCreateParcelsRequest(req) {
+    return CreateParcelsRequestFoxpostSchema.parse(req);
+}
+/**
+ * Helper to safely validate without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateCreateParcelRequest(req) {
+    return CreateParcelRequestFoxpostSchema.safeParse(req);
+}
+export function safeValidateCreateParcelsRequest(req) {
+    return CreateParcelsRequestFoxpostSchema.safeParse(req);
+}
+/**
+ * Helper to safely validate a CreateLabelRequest without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateCreateLabelRequest(req) {
+    return CreateLabelRequestFoxpostSchema.safeParse(req);
+}
+/**
+ * Helper to safely validate a CreateLabelsRequest without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateCreateLabelsRequest(req) {
+    return CreateLabelsRequestFoxpostSchema.safeParse(req);
+}
+/**
+ * Helper to safely validate a TrackingRequest without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateTrackingRequest(req) {
+    return TrackingRequestFoxpostSchema.safeParse(req);
+}
+/**
+ * Validate a Foxpost parcel payload (after mapping from canonical Parcel)
+ * Used to catch mapping errors before sending to the carrier
+ */
+export function validateFoxpostParcel(parcel) {
+    return FoxpostParcelSchema.parse(parcel);
+}
+/**
+ * Safely validate a Foxpost parcel payload without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostParcel(parcel) {
+    return FoxpostParcelSchema.safeParse(parcel);
+}
+/**
+ * ============================================================================
+ * Foxpost Tracking Schemas (from OpenAPI /api/tracking/{barcode})
+ * ============================================================================
+ */
+/**
+ * Trace enum from OpenAPI Trace.status
+ */
+const TraceStatusEnum = z.enum([
+    'CREATE',
+    'OPERIN',
+    'OPEROUT',
+    'RECEIVE',
+    'RETURN',
+    'REDIRECT',
+    'OVERTIMEOUT',
+    'SORTIN',
+    'SORTOUT',
+    'SLOTCHANGE',
+    'OVERTIMED',
+    'MPSIN',
+    'C2CIN',
+    'HDSENT',
+    'HDDEPO',
+    'HDINTRANSIT',
+    'HDRETURN',
+    'HDRECEIVE',
+    'WBXREDIRECT',
+    'BACKTOSENDER',
+    'HDHUBIN',
+    'HDHUBOUT',
+    'HDCOURIER',
+    'HDUNDELIVERABLE',
+    'PREPAREDFORPD',
+    'INWAREHOUSE',
+    'COLLECTSENT',
+    'C2BIN',
+    'RETURNED',
+    'COLLECTED',
+    'BACKLOGINFULL',
+    'BACKLOGINFAIL',
+    'MISSORT',
+    'EMPTYSLOT',
+    'RESENT',
+    'PREREDIRECT',
+]);
+/**
+ * Trace schema (from OpenAPI components/schemas/Trace)
+ *
+ * Uses lenient validation with coercion to handle real API responses:
+ * - statusDate: coerces various date string formats to Date objects
+ * - statusStationId: coerces numbers to strings (API inconsistency)
+ * - Other fields: optional, pass through extra fields
+ */
+const TraceSchema = z.object({
+    statusDate: z.string()
+        .refine((s) => {
+        // Accept any string that looks like a date
+        // Covers: ISO with timezone, ISO without timezone, other formats
+        const date = new Date(s);
+        return !isNaN(date.getTime());
+    }, "Invalid date format")
+        .transform(s => new Date(s)),
+    statusStationId: z.union([
+        z.string(),
+        z.number().transform(n => String(n)),
+    ]).optional(),
+    shortName: z.string().optional(),
+    longName: z.string().optional(),
+    status: TraceStatusEnum.optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * TrackDTO schema (from OpenAPI components/schemas/TrackDTO)
+ * Note: TrackDTO mirrors Trace but with trackId and slightly different names
+ */
+const TrackDTOSchema = z.object({
+    trackId: z.number().int().optional(),
+    status: z.string().optional(),
+    statusDate: z.string().datetime().or(z.string()).transform(s => new Date(s)),
+}).strict();
+/**
+ * Parcel type enum from OpenAPI Tracking.parcelType
+ */
+const FoxpostParcelTypeEnum = z.enum(['NORMAL', 'RE', 'XRE', 'IRE', 'C2B']);
+/**
+ * Send type enum from OpenAPI Tracking.sendType
+ */
+const FoxpostSendTypeEnum = z.enum(['APM', 'HD', 'COLLECT']);
+/**
+ * Tracking schema (from OpenAPI components/schemas/Tracking)
+ * This is the response from GET /api/tracking/{barcode}
+ *
+ * Uses lenient validation to handle API quirks:
+ * - All fields optional
+ * - estimatedDelivery can be null or string
+ * - Passes through extra fields from API
+ */
+const FoxpostTrackingSchema = z.object({
+    clFox: z.string().optional(),
+    parcelType: FoxpostParcelTypeEnum.optional(),
+    sendType: FoxpostSendTypeEnum.optional(),
+    traces: z.array(TraceSchema).optional(),
+    relatedParcel: z.string().nullable().optional(),
+    estimatedDelivery: z.string().nullable().optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * Helper to validate a Foxpost tracking response
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostTracking(res) {
+    return FoxpostTrackingSchema.parse(res);
+}
+/**
+ * Helper to safely validate a Foxpost tracking response without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostTracking(res) {
+    return FoxpostTrackingSchema.safeParse(res);
+}
+/**
+ * ============================================================================
+ * Foxpost Parcel Creation Request/Response Schemas (from OpenAPI /api/parcel)
+ * ============================================================================
+ *
+ * Schemas for request body and response shapes, modeled after Foxpost OpenAPI
+ * but kept lenient to handle real-world API quirks and future changes.
+ */
+/**
+ * FieldError schema (from OpenAPI components/schemas/FieldError)
+ * Represents a validation error on a specific field
+ * Uses lenient validation to accept any field name or error code
+ */
+const FieldErrorSchema = z.object({
+    field: z.string().optional(),
+    message: z.string().optional(),
+}).loose(); // Allow extra fields (e.g., error codes)
+/**
+ * Package schema (from OpenAPI components/schemas/Package)
+ * Represents a single parcel result in the CreateResponse
+ *
+ * Uses lenient validation:
+ * - All fields optional to handle partial responses
+ * - Passes through extra fields from carrier
+ * - Lenient with field types (clFoxId may be string or number fallback)
+ */
+const PackageSchema = z.object({
+    clFoxId: z.union([
+        z.string(),
+        z.number().transform(n => String(n)),
+    ]).optional(),
+    barcode: z.string().nullable().optional(), // Fallback name for barcode
+    newBarcode: z.string().nullable().optional(), // Alternative barcode field
+    refCode: z.string().nullable().optional(),
+    uniqueBarcode: z.string().nullable().optional(),
+    errors: z.array(FieldErrorSchema).nullable().optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * CreateResponse schema (from OpenAPI components/schemas/CreateResponse)
+ * Response from POST /api/parcel
+ *
+ * Uses lenient validation:
+ * - valid: boolean indicating if all parcels succeeded or not
+ * - parcels: array of Package results
+ * - errors: top-level validation errors (optional)
+ * - Passes through extra fields for extensibility
+ */
+const CreateResponseSchema = z.object({
+    valid: z.boolean().optional(),
+    parcels: z.array(PackageSchema).optional(),
+    errors: z.array(FieldErrorSchema).optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * CreateParcelRequest schema (from OpenAPI components/schemas/CreateParcelRequest)
+ * Request body for POST /api/parcel (single or batch)
+ *
+ * Uses lenient validation:
+ * - Required: recipientName, recipientEmail, recipientPhone (for all parcels)
+ * - HD parcels: also require recipientCity, recipientZip, recipientAddress
+ * - APM parcels: also require destination
+ * - Optional fields accept any string/value, not strict enums
+ * - size defaults to 's' if missing
+ * - cod: coerced to number, defaults to 0
+ * - Passes through extra fields for future extensibility
+ */
+const CreateParcelRequestItemSchema = z.object({
+    // Required recipient contact fields
+    recipientName: z.string().max(150).optional(),
+    recipientEmail: z.string().optional(),
+    recipientPhone: z.string().optional(),
+    // Optional contact fields
+    recipientCountry: z.string().max(3).optional(),
+    // HD (Home Delivery) address fields - optional at schema level
+    // (validation logic in parcels.ts checks that either all or none are present)
+    recipientCity: z.string().max(50).optional(),
+    recipientZip: z.string().optional(),
+    recipientAddress: z.string().max(150).optional(),
+    // APM delivery field
+    destination: z.string().optional(),
+    // Parcel details
+    size: z.union([
+        z.enum(['XS', 'S', 'M', 'L', 'XL']),
+        z.enum(['xs', 's', 'm', 'l', 'xl']).transform(s => s.toUpperCase()),
+        z.string(), // Lenient: accept any string size
+    ]).optional().default('S'),
+    cod: z.union([
+        z.number().int().min(0).max(1000000),
+        z.string().transform(s => parseInt(s, 10)).refine(n => !Number.isNaN(n) && n >= 0 && n <= 1000000),
+    ]).optional().default(0),
+    // Optional fields - lenient, any string accepted
+    comment: z.string().max(50).optional(),
+    deliveryNote: z.string().optional(),
+    label: z.boolean().optional(),
+    fragile: z.boolean().optional(),
+    refCode: z.string().max(30).optional(),
+    uniqueBarcode: z.string().max(20).optional(),
+    // Extra fields for future extensibility
+}).loose();
+/**
+ * Helper to validate a Foxpost CreateResponse
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostCreateResponse(res) {
+    return CreateResponseSchema.parse(res);
+}
+/**
+ * Helper to safely validate a Foxpost CreateResponse without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostCreateResponse(res) {
+    return CreateResponseSchema.safeParse(res);
+}
+/**
+ * Helper to validate a Foxpost Package entry
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostPackage(pkg) {
+    return PackageSchema.parse(pkg);
+}
+/**
+ * Helper to safely validate a Foxpost Package entry without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostPackage(pkg) {
+    return PackageSchema.safeParse(pkg);
+}
+/**
+ * Helper to validate a single Foxpost CreateParcelRequest item
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostCreateParcelRequestItem(item) {
+    return CreateParcelRequestItemSchema.parse(item);
+}
+/**
+ * Helper to safely validate a Foxpost CreateParcelRequest item without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostCreateParcelRequestItem(item) {
+    return CreateParcelRequestItemSchema.safeParse(item);
+}
+/**
+ * ============================================================================
+ * Foxpost Label Generation Schemas (from OpenAPI /api/label/{pageSize})
+ * ============================================================================
+ *
+ * Schemas for label generation request parameters, response metadata,
+ * error handling, and label info (from /api/label/info/{barcode})
+ */
+/**
+ * ApiError schema (from OpenAPI components/schemas/ApiError)
+ * Carrier returns this on error responses (400, 401, etc.)
+ * Uses lenient validation to accept any structure
+ */
+const ApiErrorSchema = z.object({
+    timestamp: z.string().optional(),
+    error: z.string().optional(),
+    status: z.number().int().optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * Helper to safely validate a Foxpost API error response without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostApiError(res) {
+    return ApiErrorSchema.safeParse(res);
+}
+/**
+ * PDF binary raw response validation
+ * Ensures the PDF buffer is non-empty
+ * Accepts Node Buffer or any object with numeric byteLength > 0
+ */
+const FoxpostLabelPdfRawSchema = z.any().refine((v) => {
+    return v != null && typeof v.byteLength === 'number' && v.byteLength > 0;
+}, { message: 'Expected non-empty PDF buffer' });
+/**
+ * Helper to safely validate PDF raw response without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostLabelPdfRaw(raw) {
+    return FoxpostLabelPdfRawSchema.safeParse(raw);
+}
+/**
+ * PDF metadata schema for label generation
+ * Describes the PDF file properties and generation options
+ */
+const FoxpostLabelPdfMetadataSchema = z.object({
+    size: z.enum(['A6', 'A7', '_85X85']).optional(),
+    barcodesCount: z.number().int().min(1).optional(),
+    startPos: z.number().int().min(0).max(7).optional(),
+    isPortrait: z.boolean().optional(),
+}).loose();
+/**
+ * Helper to validate PDF metadata
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostLabelPdfMetadata(metadata) {
+    return FoxpostLabelPdfMetadataSchema.parse(metadata);
+}
+/**
+ * Helper to safely validate PDF metadata without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostLabelPdfMetadata(metadata) {
+    return FoxpostLabelPdfMetadataSchema.safeParse(metadata);
+}
+/**
+ * LabelInfo schema (from OpenAPI components/schemas/LabelInfo)
+ * Response from GET /api/label/info/{barcode}
+ * Contains pre-label metadata about the parcel
+ */
+const LabelInfoSchema = z.object({
+    senderName: z.string().optional(),
+    senderZip: z.string().optional(),
+    senderCity: z.string().optional(),
+    senderAddress: z.string().optional(),
+    recipientName: z.string().optional(),
+    recipientEmail: z.string().optional(),
+    recipientPhone: z.string().optional(),
+    recipientZip: z.string().optional(),
+    recipientCity: z.string().optional(),
+    recipientAddress: z.string().optional(),
+    apm: z.string().optional(),
+    cod: z.number().int().optional(),
+    isFragile: z.boolean().optional(),
+    barcode: z.string().optional(),
+    refCode: z.string().optional(),
+    depoCode: z.string().optional(),
+    courierCode: z.string().optional(),
+    sendType: z.enum(['APM', 'HD', 'COLLECT']).optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * Helper to validate a Foxpost LabelInfo response
+ * Throws ZodError if validation fails
+ */
+export function validateFoxpostLabelInfo(res) {
+    return LabelInfoSchema.parse(res);
+}
+/**
+ * Helper to safely validate a Foxpost LabelInfo response without throwing
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostLabelInfo(res) {
+    return LabelInfoSchema.safeParse(res);
+}
+/**
+ * ============================================================================
+ * Foxpost APM/Pickup-Points Schemas (from foxplus.json feed)
+ * ============================================================================
+ */
+/**
+ * Opening hours schema - Hungarian day names with optional string values
+ * Uses passthrough to allow extra fields and lenient validation
+ */
+const OpeningHoursSchema = z.object({
+    hetfo: z.string().optional().nullable(),
+    kedd: z.string().optional().nullable(),
+    szerda: z.string().optional().nullable(),
+    csutortok: z.string().optional().nullable(),
+    pentek: z.string().optional().nullable(),
+    szombat: z.string().optional().nullable(),
+    vasarnap: z.string().optional().nullable(),
+}).loose(); // Allow extra fields
+/**
+ * Fill/empty schedule entry
+ */
+const FillEmptyEntrySchema = z.object({
+    emptying: z.string().optional(),
+    filling: z.string().optional(),
+}).loose();
+/**
+ * Foxpost APM substitute entry
+ * When a pickup point is closed or unavailable, these are alternative locations
+ * where the customer can pick up/drop off their parcel.
+ */
+const FoxpostSubstituteSchema = z.object({
+    place_id: z.union([
+        z.string(),
+        z.number().transform(n => String(n)),
+    ]),
+    operator_id: z.string().optional().nullable(),
+}).loose(); // Allow extra fields for future extensibility
+/**
+ * Foxpost APM metadata schema - carrier-specific fields
+ * Uses lenient validation with passthrough for future extensibility
+ */
+const FoxpostApmMetadataSchema = z.object({
+    depot: z.string().optional(),
+    load: z.string().optional(), // Lenient: accept any string, not just predefined enum values
+    apmType: z.string().optional(), // Lenient: accept any string (Cleveron, Keba, Rollkon, Rotte, Z-BOX, Z-Pont, etc.)
+    substitutes: z.array(FoxpostSubstituteSchema).optional(), // Array of substitute APM objects
+    variant: z.string().optional(), // Lenient: accept any string
+    fillEmptyList: z.array(FillEmptyEntrySchema).optional(),
+    ssapt: z.string().optional(),
+    sdapt: z.string().optional(),
+}).loose();
+const FoxpostApmEntrySchema = z.object({
+    place_id: z.union([
+        z.string(),
+        z.number().transform(n => String(n)),
+    ]),
+    operator_id: z.string().optional().nullable(),
+    name: z.string().optional(),
+    ssapt: z.string().optional(),
+    sdapt: z.string().optional(),
+    country: z.string().optional(),
+    address: z.string().optional(),
+    zip: z.string().optional(),
+    city: z.string().optional(),
+    street: z.string().optional(),
+    findme: z.string().optional(),
+    geolat: z.union([
+        z.number(),
+        z.string().transform(s => parseFloat(s)),
+    ]).optional().refine(n => n === undefined || !Number.isNaN(n), 'Latitude must be a valid number'),
+    geolng: z.union([
+        z.number(),
+        z.string().transform(s => parseFloat(s)),
+    ]).optional().refine(n => n === undefined || !Number.isNaN(n), 'Longitude must be a valid number'),
+    allowed2: z.enum(['ALL', 'C2C', 'B2C']).optional(),
+    depot: z.string().optional(),
+    load: z.string().optional(), // Lenient: accept any string (e.g., "normal loaded", "custom value")
+    isOutdoor: z.boolean().optional(),
+    apmType: z.string().optional(), // Lenient: accept any string (Foxpost types: Cleveron/Keba/Rollkon/Rotte, Packeta types: Z-BOX/Z-Pont, etc.)
+    substitutes: z.array(FoxpostSubstituteSchema).optional(), // Array of substitute APM objects
+    open: OpeningHoursSchema.optional(),
+    fillEmptyList: z.array(FillEmptyEntrySchema).optional(),
+    cardPayment: z.boolean().optional(),
+    cashPayment: z.boolean().optional(),
+    iconUrl: z.string().optional(),
+    variant: z.string().optional(), // Lenient: accept any string (e.g., FOXPOST A-BOX, Packeta Z-BOX, custom types)
+    paymentOptions: z.array(z.string()).optional(), // Lenient: accept any payment method string
+    paymentOptionsString: z.string().optional(),
+    service: z.array(z.string()).optional(), // Lenient: accept any service string (pickup, dispatch, or others)
+    serviceString: z.string().optional(),
+}).loose(); // Allow extra fields from API
+/**
+ * Foxpost-specific options for fetchPickupPoints.
+ *
+ * Carrier-specific filters are namespaced under `options.foxpost`.
+ */
+const FoxpostFetchPickupPointsCarrierOptionsSchema = z.object({
+    country: z.string().length(2).optional(),
+    bbox: z.object({
+        north: z.number(),
+        south: z.number(),
+        east: z.number(),
+        west: z.number(),
+    }).optional(),
+    updatedSince: z.union([z.string(), z.date()]).optional(),
+}).catchall(z.unknown());
+const FoxpostFetchPickupPointsOptionsSchema = z.object({
+    foxpost: FoxpostFetchPickupPointsCarrierOptionsSchema.optional(),
+}).catchall(z.unknown());
+const FoxpostFetchPickupPointsRequestSchema = z.object({
+    credentials: z.record(z.string(), z.unknown()).optional(),
+    options: FoxpostFetchPickupPointsOptionsSchema.optional(),
+});
+/**
+ * Helper to safely validate a Foxpost APM feed (array of entries)
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostApmFeed(feed) {
+    return z.array(FoxpostApmEntrySchema).safeParse(feed);
+}
+/**
+ * Helper to safely validate a single Foxpost APM entry
+ * Returns { success: true, data } or { success: false, error }
+ */
+export function safeValidateFoxpostApmEntry(entry) {
+    return FoxpostApmEntrySchema.safeParse(entry);
+}
+/**
+ * Helper to validate Foxpost fetchPickupPoints request envelope.
+ */
+export function safeValidateFetchPickupPointsRequest(input) {
+    return FoxpostFetchPickupPointsRequestSchema.safeParse(input);
+}