karrio-sendcloud 2025.5rc7__py3-none-any.whl

karrio/mappers/sendcloud/__init__.py

@@ -0,0 +1,20 @@
+from karrio.mappers.sendcloud.mapper import Mapper
+from karrio.mappers.sendcloud.proxy import Proxy
+from karrio.mappers.sendcloud.settings import Settings
+
+# Define METADATA here to avoid circular imports
+from karrio.core.metadata import Metadata as PluginMetadata
+import karrio.providers.sendcloud.units as units
+import karrio.providers.sendcloud.utils as utils
+
+METADATA = PluginMetadata(
+    id="sendcloud",
+    label="SendCloud",
+    Mapper=Mapper,
+    Proxy=Proxy,
+    Settings=Settings,
+    is_hub=True,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=utils.ConnectionConfig,
+)

karrio/mappers/sendcloud/mapper.py

@@ -0,0 +1,84 @@
+"""Karrio SendCloud client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.sendcloud as provider
+import karrio.mappers.sendcloud.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 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)
+    

karrio/mappers/sendcloud/proxy.py

@@ -0,0 +1,114 @@
+"""Karrio SendCloud client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.sendcloud.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/fetch-shipping-options",
+            data=request.serialize(),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/parcels",
+            data=request.serialize(),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        shipment_id = request.ctx.get("shipment_id")
+        response = lib.request(
+            url=f"{self.settings.server_url}/parcels/{shipment_id}/cancel",
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        tracking_number = request.ctx.get("tracking_number")
+        carrier = request.ctx.get("carrier", "")
+        
+        # SendCloud tracking endpoint
+        url = f"{self.settings.server_url}/tracking/{tracking_number}"
+        if carrier:
+            url = f"{url}/{carrier}"
+            
+        response = lib.request(
+            url=url,
+            trace=self.trace_as("json"),
+            method="GET",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickups",
+            data=request.serialize(),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        pickup_id = request.ctx.get("pickup_id")
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickups/{pickup_id}",
+            data=request.serialize(),
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        pickup_id = request.ctx.get("pickup_id")
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickups/{pickup_id}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+    

karrio/mappers/sendcloud/settings.py

@@ -0,0 +1,21 @@
+"""Karrio SendCloud client settings."""
+
+import attr
+import karrio.providers.sendcloud.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """SendCloud connection settings."""
+
+    # OAuth2 API connection properties
+    client_id: str
+    client_secret: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "sendcloud"
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/sendcloud/__init__.py

@@ -0,0 +1,2 @@
+# Import metadata from mappers module to avoid circular imports
+from karrio.mappers.sendcloud import METADATA

karrio/providers/sendcloud/__init__.py

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

karrio/providers/sendcloud/error.py

@@ -0,0 +1,74 @@
+"""Karrio SendCloud error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sendcloud.utils as provider_utils
+import karrio.schemas.sendcloud.error as error_schemas
+
+
+def parse_error_response(
+    response: typing.Union[dict, list],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    errors: typing.List[models.Message] = []
+    
+    # Handle dict response
+    if isinstance(response, dict):
+        # Check for error field
+        if "error" in response:
+            error_data = response["error"]
+            errors.append(
+                models.Message(
+                    carrier_id=settings.carrier_id,
+                    carrier_name=settings.carrier_name,
+                    code=error_data.get("code", "UNKNOWN"),
+                    message=error_data.get("message", "Unknown error occurred"),
+                    details={
+                        "details": error_data.get("details", ""),
+                    },
+                )
+            )
+        
+        # Check for validation errors field
+        if "errors" in response and isinstance(response["errors"], dict):
+            for field, messages in response["errors"].items():
+                for message in messages if isinstance(messages, list) else [messages]:
+                    errors.append(
+                        models.Message(
+                            carrier_id=settings.carrier_id,
+                            carrier_name=settings.carrier_name,
+                            code="VALIDATION_ERROR",
+                            message=f"{field}: {message}",
+                            details={**kwargs, "field": field},
+                        )
+                    )
+        
+        # Check for simple message field (common in APIs)
+        if not errors and "message" in response:
+            errors.append(
+                models.Message(
+                    carrier_id=settings.carrier_id,
+                    carrier_name=settings.carrier_name,
+                    code=response.get("code", "ERROR"),
+                    message=response["message"],
+                    details={**kwargs},
+                )
+            )
+    
+    # Handle list response (batch errors)
+    elif isinstance(response, list):
+        for idx, error in enumerate(response):
+            if isinstance(error, dict):
+                errors.append(
+                    models.Message(
+                        carrier_id=settings.carrier_id,
+                        carrier_name=settings.carrier_name,
+                        code=error.get("code", "ERROR"),
+                        message=error.get("message", f"Error at index {idx}"),
+                        details={**kwargs, "index": idx},
+                    )
+                )
+
+    return errors

karrio/providers/sendcloud/pickup/__init__.py

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

karrio/providers/sendcloud/pickup/cancel.py

@@ -0,0 +1,53 @@
+"""Karrio SendCloud pickup cancellation API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sendcloud.error as error
+import karrio.providers.sendcloud.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 SendCloud 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 SendCloud response"""
+    return response.get("success", False)
+    
+
+
+def pickup_cancel_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create pickup cancellation request for SendCloud API"""
+    return lib.Serializable(
+        dict(
+            confirmation_number=payload.confirmation_number,
+            reason=payload.reason,
+        ),
+        lib.to_dict,
+        ctx=dict(pickup_id=payload.confirmation_number),
+    )
+    

karrio/providers/sendcloud/pickup/create.py

@@ -0,0 +1,66 @@
+"""Karrio SendCloud pickup API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sendcloud.error as error
+import karrio.providers.sendcloud.utils as provider_utils
+
+
+def parse_pickup_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+    """Parse pickup response from SendCloud API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Extract pickup details if successful
+    pickup = _extract_details(response, settings) if not messages else None
+
+    return pickup, messages
+
+
+def _extract_details(
+    response: dict,
+    settings: provider_utils.Settings,
+) -> models.PickupDetails:
+    """Extract pickup details from SendCloud response."""
+    pickup_id = response.get("id")
+    pickup_date = response.get("pickup_date")
+    
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=str(pickup_id),
+        pickup_date=lib.fdate(pickup_date),
+        pickup_charge=lib.to_money(0),
+        ready_time=lib.ftime(response.get("ready_time")),
+        closing_time=lib.ftime(response.get("closing_time")),
+    )
+
+
+def pickup_request(
+    payload: models.PickupRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a pickup request for SendCloud API."""
+    return lib.Serializable(
+        dict(
+            pickup_date=lib.fdate(payload.pickup_date),
+            ready_time=lib.ftime(payload.ready_time),
+            closing_time=lib.ftime(payload.closing_time),
+            address=dict(
+                company_name=payload.address.company_name,
+                contact_name=payload.address.person_name,
+                address_line1=payload.address.address_line1,
+                city=payload.address.city,
+                postal_code=payload.address.postal_code,
+                country_code=payload.address.country_code,
+                phone_number=payload.address.phone_number,
+                email=payload.address.email,
+            ),
+            parcels=payload.parcels,
+        ),
+        lib.to_dict,
+    )

karrio/providers/sendcloud/pickup/update.py

@@ -0,0 +1,67 @@
+"""Karrio SendCloud pickup update API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sendcloud.error as error
+import karrio.providers.sendcloud.utils as provider_utils
+
+
+def parse_pickup_update_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+    """Parse pickup update response from SendCloud API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Extract updated pickup details
+    pickup = _extract_details(response, settings) if not messages else None
+
+    return pickup, messages
+
+
+def _extract_details(
+    response: dict,
+    settings: provider_utils.Settings,
+) -> models.PickupDetails:
+    """Extract pickup details from SendCloud response."""
+    pickup_id = response.get("id")
+    pickup_date = response.get("pickup_date")
+    
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=str(pickup_id),
+        pickup_date=lib.fdate(pickup_date),
+        pickup_charge=lib.to_money(0),
+        ready_time=lib.ftime(response.get("ready_time")),
+        closing_time=lib.ftime(response.get("closing_time")),
+    )
+
+
+def pickup_update_request(
+    payload: models.PickupUpdateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a pickup update request for SendCloud API."""
+    return lib.Serializable(
+        dict(
+            pickup_date=lib.fdate(payload.pickup_date),
+            ready_time=lib.ftime(payload.ready_time),
+            closing_time=lib.ftime(payload.closing_time),
+            address=dict(
+                company_name=payload.address.company_name,
+                contact_name=payload.address.person_name,
+                address_line1=payload.address.address_line1,
+                city=payload.address.city,
+                postal_code=payload.address.postal_code,
+                country_code=payload.address.country_code,
+                phone_number=payload.address.phone_number,
+                email=payload.address.email,
+            ),
+        ),
+        lib.to_dict,
+        ctx=dict(pickup_id=payload.confirmation_number),
+    )
+    

karrio/providers/sendcloud/rate.py

@@ -0,0 +1,139 @@
+"""Karrio SendCloud rate API implementation."""
+
+import karrio.schemas.sendcloud.rate_request as sendcloud
+import karrio.schemas.sendcloud.rate_response as rating
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.sendcloud.error as error
+import karrio.providers.sendcloud.utils as provider_utils
+import karrio.providers.sendcloud.units as provider_units
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    rates = [
+        _extract_details(option, settings) 
+        for option in response.get("data", [])
+    ]
+
+    return rates, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.RateDetails:
+    """Extract rate details from SendCloud multi-carrier response."""
+    details = lib.to_object(rating.DatumType, data)
+    
+    # Create composite service ID for hub carrier pattern
+    service_id = f"sendcloud_{details.carrier.code}_{details.product.code}"
+    
+    # Extract pricing information
+    total_charge = 0.0
+    currency = "EUR"
+    transit_days = None
+    
+    if details.quotes and len(details.quotes) > 0:
+        quote = details.quotes[0]
+        if quote.price and quote.price.total:
+            total_charge = float(quote.price.total.value or 0)
+            currency = quote.price.total.currency or "EUR"
+        transit_days = getattr(quote, 'leadtime', None)
+    
+    # Extract extra charges from breakdown
+    extra_charges = []
+    if details.quotes and len(details.quotes) > 0 and details.quotes[0].price:
+        for breakdown in details.quotes[0].price.breakdown or []:
+            if breakdown.price and float(breakdown.price.value or 0) > 0:
+                extra_charges.append(
+                    models.ChargeDetails(
+                        name=breakdown.label,
+                        amount=lib.to_money(breakdown.price.value),
+                        currency=breakdown.price.currency,
+                    )
+                )
+
+    return models.RateDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        service=service_id,
+        total_charge=lib.to_money(total_charge),
+        currency=currency,
+        transit_days=transit_days,
+        extra_charges=extra_charges,
+        meta=dict(
+            rate_provider=details.carrier.name,
+            service_name=details.name,
+            carrier_code=details.carrier.code,
+            product_code=details.product.code,
+            sendcloud_code=details.code,
+            contract_id=details.contract.id if details.contract else None,
+            # Functionalities metadata
+            signature=getattr(details.functionalities, 'signature', False),
+            tracked=getattr(details.functionalities, 'tracked', False),
+            insurance_available=getattr(details.functionalities, 'insurance', None) is not None,
+            age_check=getattr(details.functionalities, 'agecheck', None),
+            delivery_deadline=getattr(details.functionalities, 'deliverydeadline', None),
+            weekend_delivery=getattr(details.functionalities, 'weekenddelivery', None),
+            # Weight limits
+            min_weight=lib.failsafe(lambda: details.weight.min.value),
+            max_weight=lib.failsafe(lambda: details.weight.max.value),
+            weight_unit=lib.failsafe(lambda: details.weight.min.unit),
+        ),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a rate request for SendCloud's fetch-shipping-options API."""
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels)
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    # SendCloud expects total weight and dimensions
+    total_weight = sum(pkg.weight.KG for pkg in packages)
+    
+    # Get max dimensions from all packages
+    max_length = max((pkg.length.CM for pkg in packages if pkg.length), default=0)
+    max_width = max((pkg.width.CM for pkg in packages if pkg.width), default=0) 
+    max_height = max((pkg.height.CM for pkg in packages if pkg.height), default=0)
+
+    # Map data to SendCloud rate request format
+    request = sendcloud.RateRequestType(
+        fromcountry=shipper.country_code,
+        tocountry=recipient.country_code,
+        frompostalcode=shipper.postal_code,
+        topostalcode=recipient.postal_code,
+        weight=total_weight,
+        length=int(max_length) if max_length > 0 else None,
+        width=int(max_width) if max_width > 0 else None,
+        height=int(max_height) if max_height > 0 else None,
+        isreturn=lib.identity(
+            options.sendcloud_is_return.state 
+            if options.sendcloud_is_return.state is not None
+            else False
+        ),
+        requestlabelasync=lib.identity(
+            settings.connection_config.request_label_async.state
+            if settings.connection_config.request_label_async.state is not None
+            else False
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)