karrio-mydhl 2025.5rc7__py3-none-any.whl

karrio/mappers/mydhl/__init__.py

@@ -0,0 +1,3 @@
+from karrio.mappers.mydhl.mapper import Mapper
+from karrio.mappers.mydhl.proxy import Proxy
+from karrio.mappers.mydhl.settings import Settings

karrio/mappers/mydhl/mapper.py

@@ -0,0 +1,99 @@
+"""Karrio MyDHL client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.mydhl as provider
+import karrio.mappers.mydhl.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(
+        self, payload: models.RateRequest
+    ) -> lib.Serializable:
+        return provider.rate_request(payload, self.settings)
+    
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+    
+    def create_shipment_request(
+        self, payload: models.ShipmentRequest
+    ) -> lib.Serializable:
+        return provider.shipment_request(payload, self.settings)
+    
+    def create_pickup_request(
+        self, payload: models.PickupRequest
+    ) -> lib.Serializable:
+        return provider.pickup_request(payload, self.settings)
+    
+    def create_pickup_update_request(
+        self, payload: models.PickupUpdateRequest
+    ) -> lib.Serializable:
+        return provider.pickup_update_request(payload, self.settings)
+    
+    def create_cancel_pickup_request(
+        self, payload: models.PickupCancelRequest
+    ) -> lib.Serializable:
+        return provider.pickup_cancel_request(payload, self.settings)
+    
+    def create_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable[str]:
+        return provider.shipment_cancel_request(payload, self.settings)
+    
+    def create_shipment_cancel_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable[str]:
+        return provider.shipment_cancel_request(payload, self.settings)
+    
+    def create_address_validation_request(
+        self, payload: models.AddressValidationRequest
+    ) -> lib.Serializable:
+        return provider.address_validation_request(payload, self.settings)
+    
+    
+    def parse_cancel_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_cancel_response(response, self.settings)
+    
+    def parse_cancel_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+    
+    def parse_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_response(response, self.settings)
+    
+    def parse_pickup_update_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_update_response(response, self.settings)
+    
+    def parse_rate_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return provider.parse_rate_response(response, self.settings)
+    
+    def parse_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
+    
+    def parse_tracking_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)
+    
+    def parse_address_validation_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.AddressValidationDetails], typing.List[models.Message]]:
+        return provider.parse_address_validation_response(response, self.settings)
+    

karrio/mappers/mydhl/proxy.py

@@ -0,0 +1,148 @@
+"""Karrio MyDHL client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.mydhl.settings as provider_settings
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Get rates using POST /rates for multi-piece shipments."""
+        response = lib.request(
+            url=f"{self.settings.server_url}/mydhlapi/rates",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Create shipment using POST /shipments."""
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipments",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Cancel shipment using DELETE /shipments/{shipmentTrackingNumber}."""
+        data = request.serialize()
+        shipment_id = data.get("shipmentIdentifier") or data.get("shipmentId") or data.get("shipmentTrackingNumber")
+        
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipments/{shipment_id}/cancel",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable:
+        """Get tracking using GET /tracking with tracking numbers."""
+        def _get_tracking(tracking_number: str):
+            return tracking_number, lib.request(
+                url=f"{self.settings.server_url}/tracking",
+                trace=self.trace_as("json"),
+                method="GET",
+                headers={
+                    "Authorization": f"Basic {self.settings.authorization}",
+                    "Accept": "application/json",
+                },
+            )
+
+        data = request.serialize()
+        tracking_numbers = data.get("trackingNumbers", [])
+        responses = lib.run_concurently(_get_tracking, tracking_numbers)
+        return lib.Deserializable(
+            responses,
+            lambda res: [
+                (num, lib.to_dict(track)) for num, track in res if any(track.strip())
+            ],
+        )
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Schedule pickup using POST /pickups."""
+        response = lib.request(
+            url=f"{self.settings.server_url}/mydhlapi/pickups",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Update pickup using PATCH /pickups/{dispatchConfirmationNumber}."""
+        data = request.serialize()
+        dispatch_confirmation_number = data.get("dispatchConfirmationNumber")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/mydhlapi/pickups/{dispatch_confirmation_number}",
+            data=lib.to_json(data),
+            trace=self.trace_as("json"),
+            method="PATCH",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Cancel pickup using DELETE /pickups/{dispatchConfirmationNumber}."""
+        data = request.serialize()
+        dispatch_confirmation_number = data.get("dispatchConfirmationNumber")
+        requestor_name = data.get("requestorName", "System")
+        reason = data.get("reason", "Customer request")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/mydhlapi/pickups/{dispatch_confirmation_number}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+            params={
+                "requestorName": requestor_name,
+                "reason": reason,
+            },
+        )
+        return lib.Deserializable(response, lib.to_dict)
+
+    def validate_address(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Validate address using GET /address-validate."""
+        data = request.serialize()
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/mydhlapi/address-validate",
+            trace=self.trace_as("json"),
+            method="GET",
+            headers={
+                "Authorization": f"Basic {self.settings.authorization}",
+                "Accept": "application/json",
+            },
+            params=data,
+        )
+        return lib.Deserializable(response, lib.to_dict)

karrio/mappers/mydhl/settings.py

@@ -0,0 +1,24 @@
+"""Karrio MyDHL client settings."""
+
+import attr
+import jstruct
+import karrio.lib as lib
+import karrio.providers.mydhl.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """MyDHL connection settings."""
+
+    # MyDHL API credentials (required)
+    username: str                   # MyDHL API username
+    password: str                   # MyDHL API password
+    account_number: str             # MyDHL customer account number
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "mydhl"
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/mydhl/__init__.py

@@ -0,0 +1,24 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.mydhl as mappers
+import karrio.providers.mydhl.units as units
+import karrio.providers.mydhl.utils as utils
+
+
+# This METADATA object is used by Karrio to discover and register this plugin
+# when loaded through Python entrypoints or local plugin directories.
+# The entrypoint is defined in pyproject.toml under [project.entry-points."karrio.plugins"]
+METADATA = metadata.Metadata(
+    id="mydhl",
+    label="MyDHL",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    package_presets=units.PackagePresets,
+    packaging_types=units.PackagingType,
+    connection_configs=utils.ConnectionConfig,
+)

karrio/providers/mydhl/__init__.py

@@ -0,0 +1,28 @@
+"""Karrio MyDHL provider imports."""
+from karrio.providers.mydhl.utils import Settings
+from karrio.providers.mydhl.rate import (
+    parse_rate_response,
+    rate_request,
+)
+from karrio.providers.mydhl.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.mydhl.pickup import (
+    parse_pickup_cancel_response,
+    parse_pickup_response,
+    parse_pickup_update_response,
+    pickup_cancel_request,
+    pickup_request,
+    pickup_update_request,
+)
+from karrio.providers.mydhl.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.mydhl.address import (
+    parse_address_validation_response,
+    address_validation_request,
+)

karrio/providers/mydhl/address.py

@@ -0,0 +1,65 @@
+"""Karrio MyDHL address validation API implementation."""
+
+import karrio.schemas.mydhl.address_validation_request as mydhl_req
+import karrio.schemas.mydhl.address_validation_response as mydhl_res
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.mydhl.error as error
+import karrio.providers.mydhl.utils as provider_utils
+
+
+def parse_address_validation_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.AddressValidationDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    
+    # Only create validation details if there are no errors
+    validation_details = []
+    if not messages:
+        validation_details = [_extract_details(response, settings)]
+
+    return validation_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.AddressValidationDetails:
+    """Extract address validation details from MyDHL response."""
+    validation = lib.to_object(mydhl_res.AddressValidationResponseType, data)
+    
+    warnings = getattr(validation, 'warnings', []) or []
+    addresses = getattr(validation, 'address', []) or []
+    
+    return models.AddressValidationDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        success=len(warnings) == 0,
+        complete_address=models.Address(
+            city=addresses[0].cityName if addresses else "",
+            postal_code=addresses[0].postalCode if addresses else "",
+            country_code=addresses[0].countryCode if addresses else "",
+        ) if addresses else None,
+    )
+
+
+def address_validation_request(
+    payload: models.AddressValidationRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create MyDHL address validation request."""
+    address = lib.to_address(payload.address)
+
+    request = mydhl_req.AddressValidationRequestType(
+        type="delivery",
+        countryCode=address.country_code,
+        postalCode=address.postal_code,
+        cityName=address.city,
+        strictValidation=True,
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/mydhl/error.py

@@ -0,0 +1,77 @@
+"""Karrio MyDHL error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.mydhl.utils as provider_utils
+
+def parse_error_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse MyDHL error responses."""
+
+    # Handle standard error response format
+    if "detail" in response:
+        return [
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=response.get("status", ""),
+                message=response.get("detail", ""),
+                details=dict(
+                    instance=response.get("instance", ""),
+                    title=response.get("title", ""),
+                    **kwargs
+                ),
+            )
+        ]
+
+    # Handle error object format
+    if "error" in response:
+        error = response["error"]
+        return [
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=error.get("code", ""),
+                message=error.get("message", ""),
+                details=dict(
+                    details=error.get("details", ""),
+                    **kwargs
+                ),
+            )
+        ]
+
+    # Handle additional error formats if present
+    errors = response.get("errors", [])
+    additional_details = response.get("additionalDetails", [])
+
+    messages = []
+
+    # Process main errors
+    for error in errors:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=error.get("code", ""),
+                message=error.get("message", ""),
+                details=dict(error, **kwargs),
+            )
+        )
+
+    # Process additional validation errors
+    for detail in additional_details:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code="validation_error",
+                message=detail,
+                details=dict(validation_detail=detail, **kwargs),
+            )
+        )
+
+    return messages

karrio/providers/mydhl/pickup/__init__.py

@@ -0,0 +1,14 @@
+"""Karrio MyDHL pickup API imports."""
+
+from karrio.providers.mydhl.pickup.create import (
+    parse_pickup_response,
+    pickup_request,
+)
+from karrio.providers.mydhl.pickup.update import (
+    parse_pickup_update_response,
+    pickup_update_request,
+)
+from karrio.providers.mydhl.pickup.cancel import (
+    parse_pickup_cancel_response,
+    pickup_cancel_request,
+)

karrio/providers/mydhl/pickup/cancel.py

@@ -0,0 +1,62 @@
+"""Karrio MyDHL pickup cancellation API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.mydhl.error as error
+import karrio.providers.mydhl.utils as provider_utils
+
+
+def parse_pickup_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    """Parse pickup cancellation response from carrier API"""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Check if cancellation was successful
+    success = _extract_cancellation_status(response)
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=success,
+            operation="Cancel Pickup",
+        ) if success else None
+    )
+
+    return confirmation, messages
+
+
+def _extract_cancellation_status(
+    response: dict
+) -> bool:
+    """Extract cancellation success status from carrier response"""
+    
+    # Example implementation for JSON response:
+    # return response.get("status", "").lower() == "cancelled"
+
+    # For development, always return success
+    return True
+    
+
+
+def pickup_cancel_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create pickup cancellation request for carrier API"""
+    # Extract cancellation details
+    confirmation_number = payload.confirmation_number
+
+    
+    # Example implementation for JSON request:
+    request = {
+        "dispatchConfirmationNumber": confirmation_number,
+        "requestorName": getattr(payload, 'requestor_name', "System"),
+        "reason": getattr(payload, 'reason', "Customer request")
+    }
+
+    return lib.Serializable(request, lib.to_dict)
+    

karrio/providers/mydhl/pickup/create.py

@@ -0,0 +1,94 @@
+"""Karrio MyDHL pickup create API implementation."""
+
+import karrio.schemas.mydhl.pickup_create_request as mydhl_req
+import karrio.schemas.mydhl.pickup_create_response as mydhl_res
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.mydhl.error as error
+import karrio.providers.mydhl.utils as provider_utils
+
+
+def parse_pickup_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    pickup = _extract_details(response, settings) if response and not messages else None
+
+    return pickup, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.PickupDetails:
+    """Extract pickup details from MyDHL response."""
+    # For simple JSON responses, extract directly
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=data.get("confirmationNumber", ""),
+        pickup_date=lib.fdate(data.get("pickupDate")),
+        ready_time=data.get("readyTime"),
+        closing_time=data.get("closingTime"),
+    )
+
+
+def pickup_request(
+    payload: models.PickupRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create MyDHL pickup request."""
+    address = lib.to_address(payload.address)
+
+    request = mydhl_req.PickupCreateRequestType(
+        plannedPickupDateAndTime=lib.fdatetime(
+            payload.pickup_date,
+            current_format="%Y-%m-%d",
+            output_format="%Y-%m-%dT%H:%M:%S GMT+01:00"
+        ),
+        closeTime=payload.closing_time or "18:00",
+        location="reception",
+        accounts=[
+            mydhl_req.AccountType(
+                typeCode="shipper",
+                number=settings.account_number,
+            )
+        ],
+        customerDetails=mydhl_req.CustomerDetailsType(
+            shipperDetails=mydhl_req.DetailsType(
+                postalAddress=mydhl_req.PostalAddressType(
+                    cityName=address.city,
+                    countryCode=address.country_code,
+                    postalCode=address.postal_code,
+                    addressLine1=address.address_line1,
+                ),
+                contactInformation=mydhl_req.ContactInformationType(
+                    companyName=address.company_name,
+                    fullName=address.person_name,
+                    phone=address.phone_number,
+                    email=address.email,
+                ),
+            ),
+        ),
+        shipmentDetails=[
+            mydhl_req.ShipmentDetailType(
+                productCode="U",
+                packages=[
+                    mydhl_req.PackageType(
+                        weight=1.0,
+                        dimensions=mydhl_req.DimensionsType(
+                            length=1,
+                            width=1,
+                            height=1,
+                        ),
+                    )
+                ],
+            )
+        ],
+    )
+
+    return lib.Serializable(request, lib.to_dict)