karrio-easyship 2025.5rc1__py3-none-any.whl

karrio/mappers/easyship/__init__.py

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

karrio/mappers/easyship/mapper.py

@@ -0,0 +1,94 @@
+"""Karrio Easyship client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.easyship as provider
+import karrio.mappers.easyship.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_manifest_request(
+        self, payload: models.ManifestRequest
+    ) -> lib.Serializable:
+        return provider.manifest_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_manifest_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+        return provider.parse_manifest_response(response, self.settings)
+    

karrio/mappers/easyship/proxy.py

@@ -0,0 +1,155 @@
+"""Karrio Easyship client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.easyship.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/2023-01/rates",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "Content-Type": "application/json",
+                "user-agent": "app/1.0",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        # create shipment
+        response = lib.request(
+            url=f"{self.settings.server_url}/2023-01/shipments",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "Content-Type": "application/json",
+                "user-agent": "app/1.0",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        easyship_shipment_id = request.serialize().get("easyship_shipment_id")
+        response = lib.request(
+            url=f"{self.settings.server_url}/2023-01/shipments/{easyship_shipment_id}/cancel",
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "Content-Type": "application/json",
+                "user-agent": "app/1.0",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        responses = lib.run_asynchronously(
+            lambda data: (
+                data["shipment_id"],
+                lib.request(
+                    url=f"{self.settings.server_url}/2023-01/shipments/{data['shipment_id']}",
+                    trace=self.trace_as("json"),
+                    method="GET",
+                    headers={
+                        "Authorization": f"Bearer {self.settings.access_token}",
+                        "Content-Type": "application/json",
+                        "user-agent": "app/1.0",
+                    },
+                ),
+            ),
+            [_ for _ in request.serialize() if _.get("shipment_id")],
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda __: [(_[0], lib.to_dict(_[1])) for _ in __],
+        )
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/2023-01/pickups",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "Content-Type": "application/json",
+                "user-agent": "app/1.0",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = self.cancel_pickup(lib.Serializable(request.ctx))
+
+        if response.deserialize() is not None:
+            response = self.schedule_pickup(request)
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        easyship_pickup_id = request.serialize().get("easyship_pickup_id")
+        response = lib.request(
+            url=f"{self.settings.server_url}/2023-01/pickups/{easyship_pickup_id}/cancel",
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.settings.access_token}",
+                "Content-Type": "application/json",
+                "user-agent": "app/1.0",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_manifest(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        # create manifest
+        response = lib.to_dict(
+            lib.request(
+                url=f"{self.settings.server_url}/2023-01/manifests",
+                data=lib.to_json(request.serialize()),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Authorization": f"Bearer {self.settings.access_token}",
+                    "Content-Type": "application/json",
+                    "user-agent": "app/1.0",
+                },
+            )
+        )
+
+        # extract manifest url
+        manifest_url = lib.failsafe(lambda: response["manifest"]["document"]["url"])
+
+        # download manifest file
+        response.update(
+            manifest_file=lib.identity(
+                None
+                if manifest_url is None
+                else lib.request(
+                    url=manifest_url,
+                    method="GET",
+                    headers={
+                        "Authorization": f"Bearer {self.settings.access_token}",
+                        "origin": "http://localhost:5002",
+                        "user-agent": "app/1.0",
+                    },
+                    decoder=lib.encode_base64,
+                )
+            )
+        )
+
+        return lib.Deserializable(response)

karrio/mappers/easyship/settings.py

@@ -0,0 +1,20 @@
+"""Karrio Easyship client settings."""
+
+import attr
+import karrio.providers.easyship.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """Easyship connection settings."""
+
+    # Add carrier specific API connection properties here
+    access_token: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "easyship"
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/easyship/__init__.py

@@ -0,0 +1,20 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.easyship as mappers
+import karrio.providers.easyship.units as units
+import karrio.providers.easyship.utils as utils
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="easyship",
+    label="Easyship",
+    # 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/easyship/__init__.py

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

karrio/providers/easyship/error.py

@@ -0,0 +1,38 @@
+"""Karrio Easyship error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.easyship.utils as provider_utils
+
+
+def parse_error_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    errors: list = [
+        *([response["error"]] if response.get("error") else []),
+        *[
+            dict(code="warning", message=message)
+            for message in response.get("meta", {}).get("errors", [])
+        ],
+    ]
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=error.get("code"),
+            message=error.get("message"),
+            details=lib.to_dict(
+                {
+                    **kwargs,
+                    "details": error.get("details"),
+                    "request_id": error.get("request_id"),
+                    "type": error.get("type"),
+                }
+            ),
+        )
+        for error in errors
+    ]

karrio/providers/easyship/manifest.py

@@ -0,0 +1,72 @@
+"""Karrio Easyship manifest API implementation."""
+
+import karrio.schemas.easyship.manifest_request as easyship
+import karrio.schemas.easyship.manifest_response as manifests
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.easyship.error as error
+import karrio.providers.easyship.utils as provider_utils
+import karrio.providers.easyship.units as provider_units
+
+
+def parse_manifest_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    details = lib.identity(
+        _extract_details(response, settings)
+        if response.get("manifest") is not None
+        else None
+    )
+
+    return details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.ManifestDetails:
+    details = lib.to_object(manifests.ManifestType, data["manifest"])
+
+    return models.ManifestDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_id,
+        doc=models.ManifestDocument(manifest=data["manifest_file"]),
+        meta=dict(
+            courier_umbrella_name=details.courier_umbrella_name,
+            courier_account_id=details.courier_account_id,
+            manifest_url=details.document.url,
+            reference=details.ref_number,
+            manifest_id=details.id,
+        ),
+    )
+
+
+def manifest_request(
+    payload: models.ManifestRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "ManifestOptions",
+            {
+                "easyship_courier_account_id": lib.OptionEnum(
+                    "easyship_courier_account_id"
+                ),
+            },
+        ),
+    )
+
+    # map data to convert karrio model to easyship specific type
+    request = easyship.ManifestRequestType(
+        courier_account_id=options.easyship_courier_account_id.state,
+        shipment_ids=payload.shipment_identifiers,
+    )
+
+    return lib.Serializable(request, lib.to_dict)