karrio-sapient 2025.5rc1__py3-none-any.whl

karrio/mappers/sapient/__init__.py

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

karrio/mappers/sapient/mapper.py

@@ -0,0 +1,69 @@
+"""Karrio SAPIENT client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.sapient as provider
+import karrio.mappers.sapient.settings as provider_settings
+import karrio.universal.providers.rating as universal_provider
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return universal_provider.rate_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 universal_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)

karrio/mappers/sapient/proxy.py

@@ -0,0 +1,87 @@
+"""Karrio SAPIENT client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.providers.sapient.utils as provider_utils
+import karrio.mappers.sapient.settings as provider_settings
+import karrio.universal.mappers.rating_proxy as rating_proxy
+
+
+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 create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/v4/shipments/{request.ctx['carrier_code']}",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "user-agent": "Karrio/1.0",
+            },
+            on_error=provider_utils.parse_error_response,
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/v4/shipments/status",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "user-agent": "Karrio/1.0",
+            },
+            on_ok=lambda _: '{"ok": true}',
+            on_error=provider_utils.parse_error_response,
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/v4/collections/{request.ctx['carrier_code']}/{request.ctx['shipmentId']}",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "user-agent": "Karrio/1.0",
+            },
+            on_error=provider_utils.parse_error_response,
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = self.cancel_pickup(lib.Serializable(request.ctx))
+
+        if response.deserialize()["ok"]:
+            response = self.schedule_pickup(request)
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        payload = request.serialize()
+        response = lib.request(
+            url=f"{self.settings.server_url}/v4/collections/{payload['carrier_code']}/{payload['shipmentId']}/cancel",
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "user-agent": "Karrio/1.0",
+            },
+            on_error=provider_utils.parse_error_response,
+        )
+
+        return lib.Deserializable(response, lib.to_dict)

karrio/mappers/sapient/settings.py

@@ -0,0 +1,36 @@
+"""Karrio SAPIENT client settings."""
+
+import attr
+import typing
+import jstruct
+import karrio.core.models as models
+import karrio.providers.sapient.utils as provider_utils
+import karrio.providers.sapient.units as provider_units
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """SAPIENT connection settings."""
+
+    # Add carrier specific API connection properties here
+    client_id: str
+    client_secret: str
+    shipping_account_id: str
+    sapient_carrier_code: provider_utils.SapientCarrierCode = "RM"  # type: ignore
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "sapient"
+    account_country_code: str = "GB"
+    metadata: dict = {}
+    config: dict = {}
+
+    services: typing.List[models.ServiceLevel] = jstruct.JList[models.ServiceLevel, False, dict(default=provider_units.DEFAULT_SERVICES)]  # type: ignore
+
+    @property
+    def shipping_services(self) -> typing.List[models.ServiceLevel]:
+        if any(self.services or []):
+            return self.services
+
+        return provider_units.DEFAULT_SERVICES

karrio/plugins/sapient/__init__.py

@@ -0,0 +1,20 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.sapient as mappers
+import karrio.providers.sapient.units as units
+import karrio.providers.sapient.utils as utils
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="sapient",
+    label="SAPIENT",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=True,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=utils.ConnectionConfig,
+)

karrio/providers/sapient/__init__.py

@@ -0,0 +1,18 @@
+"""Karrio SAPIENT provider imports."""
+
+from karrio.providers.sapient.utils import Settings
+
+from karrio.providers.sapient.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.sapient.pickup import (
+    parse_pickup_cancel_response,
+    parse_pickup_update_response,
+    parse_pickup_response,
+    pickup_update_request,
+    pickup_cancel_request,
+    pickup_request,
+)

karrio/providers/sapient/error.py

@@ -0,0 +1,28 @@
+"""Karrio SAPIENT error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sapient.utils as provider_utils
+
+
+def parse_error_response(
+    response: typing.Union[dict, typing.List[dict]],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    responses = response if isinstance(response, list) else [response]
+    errors: typing.List[dict] = sum(
+        [_["Errors"] for _ in responses if "Errors" in _], []
+    )
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=error.get("ErrorCode", "UNKNOWN"),
+            message=error.get("Message", "Unknown error"),
+            details=lib.to_dict({**kwargs, "Cause": error.get("Cause")}),
+        )
+        for error in errors
+    ]

karrio/providers/sapient/pickup/__init__.py

@@ -0,0 +1,4 @@
+
+from karrio.providers.sapient.pickup.create import parse_pickup_response, pickup_request
+from karrio.providers.sapient.pickup.update import parse_pickup_update_response, pickup_update_request
+from karrio.providers.sapient.pickup.cancel import parse_pickup_cancel_response, pickup_cancel_request

karrio/providers/sapient/pickup/cancel.py

@@ -0,0 +1,57 @@
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.sapient.error as error
+import karrio.providers.sapient.utils as provider_utils
+import karrio.providers.sapient.units as provider_units
+
+
+def parse_pickup_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    success = True  # compute address validation success state
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Pickup",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def pickup_cancel_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "sapient_carrier_code": lib.OptionEnum("sapient_carrier_code"),
+                "sapient_shipment_id": lib.OptionEnum("sapient_shipment_id"),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to sapient specific type
+    request = dict(
+        shipmentId=options.sapient_shipment_id.state,
+        carrier_code=lib.identity(
+            options.sapient_carrier_code.state or settings.sapient_carrier_code
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/sapient/pickup/create.py

@@ -0,0 +1,87 @@
+import karrio.schemas.sapient.pickup_request as sapient
+import karrio.schemas.sapient.pickup_response as pickup
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.sapient.error as error
+import karrio.providers.sapient.utils as provider_utils
+import karrio.providers.sapient.units as provider_units
+
+
+def parse_pickup_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.PickupDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    pickup = lib.identity(
+        _extract_details(response, settings, _response.ctx)
+        if "CollectionOrderId" in response
+        else None
+    )
+
+    return pickup, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict = None,
+) -> models.PickupDetails:
+    details = lib.to_object(pickup.PickupResponseType, data)
+
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=details.CollectionOrderId,
+        pickup_date=lib.fdate(details.CollectionDate),
+        meta=dict(
+            sapient_shipment_id=ctx.get("shipmentId"),
+            sapient_carrier_code=ctx.get("carrier_code"),
+        ),
+    )
+
+
+def pickup_request(
+    payload: models.PickupRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "sapient_shipment_id": lib.OptionEnum("sapient_shipment_id"),
+                "sapient_carrier_code": lib.OptionEnum("sapient_carrier_code"),
+                "sapient_bring_my_label": lib.OptionEnum("BringMyLabel"),
+                "sapient_slot_reservation_id": lib.OptionEnum("SlotReservationId"),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to sapient specific type
+    request = sapient.PickupRequestType(
+        SlotDate=payload.pickup_date,
+        SlotReservationId=options.sapient_slot_reservation_id.state,
+        BringMyLabel=lib.identity(
+            options.sapient_bring_my_label.state
+            if options.sapient_bring_my_label.state is not None
+            else False
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lib.to_dict,
+        dict(
+            shipmentId=options.sapient_shipment_id.state,
+            carrier_code=lib.identity(
+                options.sapient_carrier_code.state or settings.sapient_carrier_code
+            ),
+        ),
+    )

karrio/providers/sapient/pickup/update.py

@@ -0,0 +1,87 @@
+import karrio.schemas.sapient.pickup_request as sapient
+import karrio.schemas.sapient.pickup_response as pickup
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.sapient.error as error
+import karrio.providers.sapient.utils as provider_utils
+import karrio.providers.sapient.units as provider_units
+
+
+def parse_pickup_update_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.PickupDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings, _response.ctx)
+    pickup = lib.identity(
+        _extract_details(response, settings)
+        if "confirmation_number" in response
+        else None
+    )
+
+    return pickup, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict = None,
+) -> models.PickupDetails:
+    details = lib.to_object(pickup.PickupResponseType, data)
+
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=details.CollectionOrderId,
+        pickup_date=lib.fdate(details.CollectionDate),
+        meta=dict(
+            sapient_shipment_id=ctx.get("shipmentId"),
+            sapient_carrier_code=ctx.get("carrier_code"),
+        ),
+    )
+
+
+def pickup_update_request(
+    payload: models.PickupUpdateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "sapient_shipment_id": lib.OptionEnum("shipment_id"),
+                "sapient_carrier_code": lib.OptionEnum("sapient_carrier_code"),
+                "sapient_slot_reservation_id": lib.OptionEnum("SlotReservationId"),
+                "sapient_bring_my_label": lib.OptionEnum("BringMyLabel", bool),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to sapient specific type
+    request = sapient.PickupRequestType(
+        SlotDate=payload.pickup_date,
+        SlotReservationId=options.sapient_slot_reservation_id.state,
+        BringMyLabel=lib.identity(
+            options.sapient_bring_my_label.state
+            if options.sapient_bring_my_label.state is not None
+            else False
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lib.to_dict,
+        dict(
+            shipmentId=options.sapient_shipment_id.state,
+            carrier_code=lib.identity(
+                options.sapient_carrier_code.state or settings.sapient_carrier_code
+            ),
+        ),
+    )

karrio/providers/sapient/shipment/__init__.py

@@ -0,0 +1,9 @@
+
+from karrio.providers.sapient.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.sapient.shipment.cancel import (
+    parse_shipment_cancel_response,
+    shipment_cancel_request,
+)

karrio/providers/sapient/shipment/cancel.py

@@ -0,0 +1,57 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.sapient.error as error
+import karrio.providers.sapient.utils as provider_utils
+import karrio.providers.sapient.units as provider_units
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    success = response.get("ok") is True
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Shipment",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "reason": lib.OptionEnum("Reason"),
+                "shipment_ids": lib.OptionEnum("ShipmentIds", list),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to sapient specific type
+    request = dict(
+        Status="Cancel",
+        Reason=options.reason.state or "Order Cancelled",
+        ShipmentIds=lib.identity(
+            options.shipment_ids.state or [payload.shipment_identifier]
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)