karrio-hermes 2026.1__py3-none-any.whl

karrio/mappers/hermes/__init__.py

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

karrio/mappers/hermes/mapper.py

@@ -0,0 +1,59 @@
+"""Karrio Hermes client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.hermes as provider
+import karrio.mappers.hermes.settings as provider_settings
+import karrio.universal.providers.rating as universal_provider
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    # Rating operations (using rate sheets)
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return universal_provider.rate_request(payload, self.settings)
+
+    def parse_rate_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return universal_provider.parse_rate_response(response, self.settings)
+
+    # Shipment operations
+    def create_shipment_request(
+        self, payload: models.ShipmentRequest
+    ) -> lib.Serializable:
+        return provider.shipment_request(payload, 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)
+
+    # Pickup operations
+    def create_pickup_request(
+        self, payload: models.PickupRequest
+    ) -> lib.Serializable:
+        return provider.pickup_request(payload, 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 create_cancel_pickup_request(
+        self, payload: models.PickupCancelRequest
+    ) -> lib.Serializable:
+        return provider.pickup_cancel_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)
+
+    # Note: Hermes API does not support:
+    # - cancel_shipment (no DELETE endpoint for shipments)
+    # - pickup_update (no PUT endpoint for pickups)
+    

karrio/mappers/hermes/proxy.py

@@ -0,0 +1,78 @@
+"""Karrio Hermes client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.hermes.settings as provider_settings
+import karrio.universal.mappers.rating_proxy as rating_proxy
+from karrio.providers.hermes.units import LabelType
+
+
+class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        return super().get_rates(request)
+
+    def _get_headers(self, accept: str = "application/json") -> dict:
+        """Get common headers for Hermes API requests."""
+        token_data = self.settings.access_token
+        # Handle case where token_data might not be a dict
+        access_token = token_data.get("access_token") if isinstance(token_data, dict) else token_data
+        language = self.settings.connection_config.language.state or "DE"
+
+        return {
+            "Content-Type": "application/json",
+            "Accept": accept,
+            "Accept-Language": language,
+            "Authorization": f"Bearer {access_token}",
+        }
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Create a shipment order with label.
+
+        Endpoint: POST /shipmentorders/labels
+        """
+        label_type = self.settings.connection_config.label_type.state or "PDF"
+        accept_header = LabelType.map(label_type).value or "application/pdf"
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipmentorders/labels",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers=self._get_headers(accept=accept_header),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Create a pickup order.
+
+        Endpoint: POST /pickuporders
+        """
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickuporders",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers=self._get_headers(),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Cancel a pickup order.
+
+        Endpoint: DELETE /pickuporders/{pickupOrderID}
+        """
+        payload = request.serialize()
+        pickup_order_id = payload.get("pickupOrderID")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickuporders/{pickup_order_id}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers=self._get_headers(),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)

karrio/mappers/hermes/settings.py

@@ -0,0 +1,36 @@
+"""Karrio Hermes client settings."""
+
+import attr
+import typing
+import jstruct
+import karrio.core.models as models
+import karrio.providers.hermes.units as provider_units
+import karrio.providers.hermes.utils as provider_utils
+import karrio.universal.mappers.rating_proxy as rating_proxy
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings, rating_proxy.RatingMixinSettings):
+    """Hermes connection settings."""
+
+    # OAuth2 credentials (password flow)
+    username: str  # type:ignore
+    password: str  # type:ignore
+    client_id: str  # type:ignore
+    client_secret: str  # type:ignore
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "hermes"
+    services: typing.List[models.ServiceLevel] = jstruct.JList[models.ServiceLevel, False, dict(default=provider_units.DEFAULT_SERVICES)]  # type: ignore
+    account_country_code: str = "DE"
+    metadata: dict = {}
+    config: dict = {}
+
+    @property
+    def shipping_services(self) -> typing.List[models.ServiceLevel]:
+        if any(self.services or []):
+            return self.services
+
+        return provider_units.DEFAULT_SERVICES

karrio/plugins/hermes/__init__.py

@@ -0,0 +1,29 @@
+from karrio.core.metadata import PluginMetadata
+
+from karrio.mappers.hermes.mapper import Mapper
+from karrio.mappers.hermes.proxy import Proxy
+from karrio.mappers.hermes.settings import Settings
+import karrio.providers.hermes.units as units
+
+
+# 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 = PluginMetadata(
+    id="hermes",
+    label="Hermes",
+    description="Hermes shipping integration for Karrio",
+    # Integrations
+    Mapper=Mapper,
+    Proxy=Proxy,
+    Settings=Settings,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    service_levels=units.DEFAULT_SERVICES,
+    connection_configs=units.ConnectionConfig,
+    # Extra info
+    website="https://www.hermesworld.com",
+    documentation="https://de-api-int.hermesworld.com/docs/applications/order",
+)

karrio/providers/hermes/__init__.py

@@ -0,0 +1,16 @@
+"""Karrio Hermes provider imports."""
+from karrio.providers.hermes.utils import Settings
+from karrio.providers.hermes.shipment import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.hermes.pickup import (
+    parse_pickup_cancel_response,
+    parse_pickup_response,
+    pickup_cancel_request,
+    pickup_request,
+)
+
+# Note: Hermes API does not support:
+# - shipment cancellation (no DELETE endpoint for shipments)
+# - pickup update (no PUT endpoint for pickups)

karrio/providers/hermes/error.py

@@ -0,0 +1,94 @@
+"""Karrio Hermes error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.hermes.utils as provider_utils
+
+
+def parse_error_response(
+    response: typing.Union[dict, str, None],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse Hermes error response into karrio messages."""
+    messages: typing.List[models.Message] = []
+
+    if response is None:
+        return messages
+
+    # Handle case where response is not a dict (e.g., raw string response)
+    if not isinstance(response, dict):
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code="PARSE_ERROR",
+                message=f"Unexpected response format: {str(response)[:200]}",
+                details={**kwargs},
+            )
+        )
+        return messages
+
+    # Handle OAuth2 error response
+    if "error" in response:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=response.get("error", "AUTH_ERROR"),
+                message=response.get("error_description", "Authentication failed"),
+                details={**kwargs},
+            )
+        )
+
+    # Handle Hermes API error response with listOfResultCodes
+    result_codes = response.get("listOfResultCodes") or []
+    for error in result_codes:
+        code = error.get("code", "")
+        message = error.get("message", "")
+
+        # Only include actual errors (codes starting with 'e')
+        if code.startswith("e") or (code and not code.startswith("w")):
+            messages.append(
+                models.Message(
+                    carrier_id=settings.carrier_id,
+                    carrier_name=settings.carrier_name,
+                    code=code,
+                    message=message,
+                    details={**kwargs},
+                )
+            )
+
+    return messages
+
+
+def parse_warning_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse Hermes warning response into karrio messages."""
+    messages: typing.List[models.Message] = []
+
+    if response is None:
+        return messages
+
+    # Handle warnings from listOfResultCodes (codes starting with 'w')
+    result_codes = response.get("listOfResultCodes") or []
+    for warning in result_codes:
+        code = warning.get("code", "")
+        message = warning.get("message", "")
+
+        if code.startswith("w"):
+            messages.append(
+                models.Message(
+                    carrier_id=settings.carrier_id,
+                    carrier_name=settings.carrier_name,
+                    code=code,
+                    message=message,
+                    details={**kwargs},
+                )
+            )
+
+    return messages

karrio/providers/hermes/pickup/__init__.py

@@ -0,0 +1,12 @@
+"""Karrio Hermes pickup API imports."""
+
+from karrio.providers.hermes.pickup.create import (
+    parse_pickup_response,
+    pickup_request,
+)
+from karrio.providers.hermes.pickup.cancel import (
+    parse_pickup_cancel_response,
+    pickup_cancel_request,
+)
+
+# Note: Hermes API does not support pickup update

karrio/providers/hermes/pickup/cancel.py

@@ -0,0 +1,49 @@
+"""Karrio Hermes pickup cancellation API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.hermes.error as error
+import karrio.providers.hermes.utils as provider_utils
+
+
+def parse_pickup_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ConfirmationDetails], typing.List[models.Message]]:
+    """Parse Hermes pickup cancellation response."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Check if cancellation was successful (no errors means success)
+    success = len(messages) == 0
+
+    confirmation = None
+    if success:
+        confirmation = models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=True,
+            operation="Cancel Pickup",
+        )
+
+    return confirmation, messages
+
+
+def pickup_cancel_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create Hermes pickup cancellation request.
+
+    Note: The pickup order ID is passed in the URL path, not in the body.
+    The proxy.cancel_pickup method extracts pickupOrderID from the payload.
+    """
+    # Hermes uses DELETE /pickuporders/{pickupOrderID}
+    # The confirmation_number from Karrio is the pickupOrderID
+    request = {
+        "pickupOrderID": payload.confirmation_number,
+    }
+
+    return lib.Serializable(request, lib.to_dict)
+    

karrio/providers/hermes/pickup/create.py

@@ -0,0 +1,98 @@
+"""Karrio Hermes pickup scheduling implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.hermes.error as error
+import karrio.providers.hermes.utils as provider_utils
+import karrio.schemas.hermes.pickup_create_request as hermes_req
+import karrio.schemas.hermes.pickup_create_response as hermes_res
+
+
+def parse_pickup_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.PickupDetails], typing.List[models.Message]]:
+    """Parse Hermes pickup response."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Check if we have a valid pickup order ID
+    pickup = None
+    if response.get("pickupOrderID"):
+        pickup = _extract_details(response, settings)
+
+    return pickup, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.PickupDetails:
+    """Extract pickup details from Hermes response."""
+    response = lib.to_object(hermes_res.PickupCreateResponseType, data)
+
+    # Hermes returns pickupOrderID as the confirmation number
+    confirmation_number = response.pickupOrderID or ""
+
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=confirmation_number,
+        pickup_date=None,  # Not returned in response
+    )
+
+
+def pickup_request(
+    payload: models.PickupRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a Hermes pickup request."""
+    address = lib.to_address(payload.address)
+
+    # Parse parcel counts by size (XS, S, M, L, XL)
+    # Default to counting all parcels as M (medium) if not specified
+    parcel_count = hermes_req.ParcelCountType(
+        pickupParcelCountXS=0,
+        pickupParcelCountS=0,
+        pickupParcelCountM=len(payload.parcels) if payload.parcels else 1,
+        pickupParcelCountL=0,
+        pickupParcelCountXL=0,
+    )
+
+    # Map time slot from ready_time/closing_time
+    # Valid values per OpenAPI: BETWEEN_10_AND_13, BETWEEN_12_AND_15, BETWEEN_14_AND_17
+    time_slot = None
+    if payload.ready_time:
+        hour = int(payload.ready_time.split(":")[0]) if ":" in payload.ready_time else 12
+        if hour < 12:
+            time_slot = "BETWEEN_10_AND_13"
+        elif hour < 14:
+            time_slot = "BETWEEN_12_AND_15"
+        else:
+            time_slot = "BETWEEN_14_AND_17"
+
+    # Create the request using generated schema types
+    request = hermes_req.PickupCreateRequestType(
+        pickupAddress=hermes_req.PickupAddressType(
+            street=address.street_name,
+            houseNumber=address.street_number or "",
+            zipCode=address.postal_code,
+            town=address.city,
+            countryCode=address.country_code,
+            addressAddition=address.address_line2 or address.company_name or None,
+        ),
+        pickupName=hermes_req.PickupNameType(
+            title=None,
+            gender=None,
+            firstname=address.person_name.split()[0] if address.person_name else None,
+            middlename=None,
+            lastname=" ".join(address.person_name.split()[1:]) if address.person_name and len(address.person_name.split()) > 1 else address.person_name,
+        ),
+        phone=address.phone_number or None,
+        pickupDate=payload.pickup_date,
+        pickupTimeSlot=time_slot,
+        parcelCount=parcel_count,
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/hermes/shipment/__init__.py

@@ -0,0 +1,8 @@
+"""Karrio Hermes shipment API imports."""
+
+from karrio.providers.hermes.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+
+# Note: Hermes API does not support shipment cancellation