karrio-easypost 2025.5rc1__py3-none-any.whl

karrio/mappers/easypost/__init__.py

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

karrio/mappers/easypost/mapper.py

@@ -0,0 +1,67 @@
+from typing import List, Tuple
+from karrio.api.mapper import Mapper as BaseMapper
+from karrio.mappers.easypost.settings import Settings
+from karrio.core.utils.serializable import Deserializable, Serializable
+from karrio.core.models import (
+    RateRequest,
+    ShipmentRequest,
+    ShipmentDetails,
+    ShipmentCancelRequest,
+    RateDetails,
+    Message,
+    ConfirmationDetails,
+    TrackingDetails,
+    TrackingRequest,
+)
+from karrio.providers.easypost import (
+    parse_shipment_cancel_response,
+    parse_tracking_response,
+    parse_shipment_response,
+    parse_rate_response,
+    shipment_cancel_request,
+    tracking_request,
+    shipment_request,
+    rate_request,
+)
+
+
+class Mapper(BaseMapper):
+    settings: Settings
+
+    # Request Mappers
+
+    def create_rate_request(self, payload: RateRequest) -> Serializable:
+        return rate_request(payload, self.settings)
+
+    def create_shipment_request(self, payload: ShipmentRequest) -> Serializable:
+        return shipment_request(payload, self.settings)
+
+    def create_cancel_shipment_request(
+        self, payload: ShipmentCancelRequest
+    ) -> Serializable:
+        return shipment_cancel_request(payload, self.settings)
+
+    def create_tracking_request(self, payload: TrackingRequest) -> Serializable:
+        return tracking_request(payload, self.settings)
+
+    # Response Parsers
+
+    def parse_rate_response(
+        self, response: Deserializable
+    ) -> Tuple[List[RateDetails], List[Message]]:
+        return parse_rate_response(response, self.settings)
+
+    def parse_shipment_response(
+        self, response: Deserializable
+    ) -> Tuple[ShipmentDetails, List[Message]]:
+        return parse_shipment_response(response, self.settings)
+
+    def parse_cancel_shipment_response(
+        self, response: Deserializable
+    ) -> Tuple[ConfirmationDetails, List[Message]]:
+        return parse_shipment_cancel_response(response, self.settings)
+
+    def parse_tracking_response(
+        self, response: Deserializable
+    ) -> Tuple[List[TrackingDetails], List[Message]]:
+        return parse_tracking_response(response, self.settings)

karrio/mappers/easypost/proxy.py

@@ -0,0 +1,100 @@
+import typing
+import karrio.lib as lib
+import karrio.api.proxy as base
+import karrio.mappers.easypost.settings as provider_settings
+
+
+class Proxy(base.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable:
+        response = self._send_request(
+            path="/shipments",
+            request=lib.Serializable(request.serialize(), lib.to_json),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        payload = request.serialize()
+
+        def create(request) -> str:
+            response = lib.to_dict(
+                self._send_request(
+                    path="/shipments", request=lib.Serializable(request, lib.to_json)
+                )
+            )
+
+            if "error" in response:
+                return response
+
+            # retrieve rate with the selected service.
+            rate_id = next(
+                (
+                    rate["id"]
+                    for rate in response.get("rates", [])
+                    if rate["service"] == payload["service"]
+                ),
+                None,
+            )
+            data = lib.to_dict(
+                {
+                    "rate": {"id": rate_id},
+                    "insurance": payload.get("insurance"),
+                }
+            )
+
+            if rate_id is None:
+                raise Exception("No rate found for the given service.")
+
+            return self._send_request(
+                path=f"/shipments/{response['id']}/buy",
+                request=lib.Serializable(data, lib.to_json),
+            )
+
+        response = create(payload["data"])
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        response = self._send_request(path=f"/shipments/{request.serialize()}/refund")
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, requests: lib.Serializable) -> lib.Deserializable:
+        track = lambda request: (
+            request["tracking_code"],
+            self._send_request(
+                **(
+                    dict(
+                        path="/trackers", request=lib.Serializable(request, lib.to_json)
+                    )
+                    if request.get("tracker_id") is None
+                    else dict(path=f"/trackers/{request['tracker_id']}", method="GET")
+                )
+            ),
+        )
+
+        responses: typing.List[typing.Tuple[str, str]] = lib.run_asynchronously(
+            track, requests.serialize()
+        )
+        return lib.Deserializable(
+            responses,
+            lambda res: [(key, lib.to_dict(response)) for key, response in res],
+        )
+
+    def _send_request(
+        self, path: str, request: lib.Serializable = None, method: str = "POST"
+    ) -> str:
+        data: dict = dict(data=request.serialize()) if request is not None else dict()
+        return lib.request(
+            **{
+                "url": f"{self.settings.server_url}{path}",
+                "trace": self.trace_as("json"),
+                "method": method,
+                "headers": {
+                    "Content-Type": "application/json",
+                    "Authorization": f"Basic {self.settings.authorization}",
+                },
+                **data,
+            }
+        )

karrio/mappers/easypost/settings.py

@@ -0,0 +1,18 @@
+"""Karrio EasyPost connection settings."""
+
+import attr
+from karrio.providers.easypost.utils import Settings as BaseSettings
+
+
+@attr.s(auto_attribs=True)
+class Settings(BaseSettings):
+    """EasyPost connection settings."""
+
+    api_key: str
+
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "easypost"
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/easypost/__init__.py

@@ -0,0 +1,19 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.easypost as mappers
+import karrio.providers.easypost.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="easypost",
+    label="EasyPost",
+    is_hub=True,
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    options=units.ShippingOption,
+    services=units.Service,
+    hub_carriers=units.CarrierId.to_dict(),
+)

karrio/providers/easypost/__init__.py

@@ -0,0 +1,8 @@
+from karrio.providers.easypost.rate import parse_rate_response, rate_request
+from karrio.providers.easypost.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.easypost.tracking import parse_tracking_response, tracking_request

karrio/providers/easypost/error.py

@@ -0,0 +1,31 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.easypost.utils as provider_utils
+
+
+def parse_error_response(
+    response: dict, settings: provider_utils.Settings, **kwargs
+) -> typing.List[models.Message]:
+    errors = [
+        *response.get("messages", []),
+        *([response.get("error")] if "error" in response else []),
+    ]
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=(error.get("code") or error.get("type")),
+            message=error.get("message"),
+            details=lib.to_dict(
+                {
+                    "errors": error.get("errors"),
+                    "carrier": error.get("carrier"),
+                    "carrier_account_id": error.get("carrier_account_id"),
+                    **kwargs,
+                }
+            ),
+        )
+        for error in errors
+    ]

karrio/providers/easypost/rate.py

@@ -0,0 +1,194 @@
+import karrio.schemas.easypost.shipment_request as easypost
+from karrio.schemas.easypost.shipments_response import Shipment
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.easypost.error as provider_error
+import karrio.providers.easypost.units as provider_units
+import karrio.providers.easypost.utils as provider_utils
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.RateDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    errors = provider_error.parse_error_response(response, settings)
+    rates = _extract_details(response, settings) if "error" not in response else []
+
+    return rates, errors
+
+
+def _extract_details(
+    response: dict,
+    settings: provider_utils.Settings,
+) -> typing.List[models.RateDetails]:
+    rates = lib.to_object(Shipment, response).rates
+
+    return [
+        (
+            lambda rate_provider, service, service_name: models.RateDetails(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                service=service,
+                currency=rate.currency,
+                total_charge=lib.to_decimal(rate.rate),
+                transit_days=rate.delivery_days,
+                meta=dict(
+                    service_name=service_name,
+                    rate_provider=rate_provider,
+                ),
+            )
+        )(*provider_units.Service.info(rate.service, rate.carrier))
+        for rate in rates
+    ]
+
+
+def rate_request(payload: models.RateRequest, _) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    return_address = lib.to_address(payload.return_address)
+    billing_address = lib.to_address(payload.billing_address)
+    package = lib.to_packages(
+        payload.parcels,
+        package_option_type=provider_units.ShippingOption,
+    ).single
+    options = lib.to_shipping_options(
+        payload,
+        package_options=package.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    is_intl = shipper.country_code != recipient.country_code
+    customs = (
+        models.Customs(
+            commodities=(
+                package.parcel.items
+                if any(package.parcel.items)
+                else [
+                    models.Commodity(
+                        sku="0000",
+                        quantity=1,
+                        weight=package.weight.value,
+                        weight_unit=package.weight_unit.value,
+                    )
+                ]
+            )
+        )
+        if is_intl
+        else None
+    )
+
+    requests = easypost.ShipmentRequest(
+        shipment=easypost.Shipment(
+            reference=payload.reference,
+            to_address=easypost.Address(
+                company=recipient.company_name,
+                street1=recipient.street,
+                street2=recipient.address_line2,
+                city=recipient.city,
+                state=recipient.state_code,
+                zip=recipient.postal_code,
+                country=recipient.country_code,
+                residential=recipient.residential,
+                name=recipient.person_name,
+                phone=recipient.phone_number,
+                email=recipient.email,
+                federal_tax_id=recipient.federal_tax_id,
+                state_tax_id=recipient.state_tax_id,
+            ),
+            from_address=easypost.Address(
+                company=shipper.company_name,
+                street1=shipper.street,
+                street2=shipper.address_line2,
+                city=shipper.city,
+                state=shipper.state_code,
+                zip=shipper.postal_code,
+                country=shipper.country_code,
+                residential=shipper.residential,
+                name=shipper.person_name,
+                phone=shipper.phone_number,
+                email=shipper.email,
+                federal_tax_id=shipper.federal_tax_id,
+                state_tax_id=shipper.state_tax_id,
+            ),
+            return_address=lib.identity(
+                easypost.Address(
+                    company=return_address.company_name,
+                    street1=return_address.street,
+                    street2=return_address.address_line2,
+                    city=return_address.city,
+                    state=return_address.state_code,
+                    zip=return_address.postal_code,
+                    country=return_address.country_code,
+                    residential=return_address.residential,
+                    name=return_address.person_name,
+                    phone=return_address.phone_number,
+                    email=return_address.email,
+                    federal_tax_id=return_address.federal_tax_id,
+                    state_tax_id=return_address.state_tax_id,
+                )
+                if payload.return_address
+                else None
+            ),
+            buyer_address=lib.identity(
+                easypost.Address(
+                    company=billing_address.company_name,
+                    street1=billing_address.street,
+                    street2=billing_address.address_line2,
+                    city=billing_address.city,
+                    state=billing_address.state_code,
+                    zip=billing_address.postal_code,
+                    country=billing_address.country_code,
+                    residential=billing_address.residential,
+                    name=billing_address.person_name,
+                    phone=billing_address.phone_number,
+                    email=billing_address.email,
+                    federal_tax_id=billing_address.federal_tax_id,
+                    state_tax_id=billing_address.state_tax_id,
+                )
+                if payload.billing_address
+                else None
+            ),
+            parcel=easypost.Parcel(
+                length=package.length.IN,
+                width=package.width.IN,
+                height=package.height.IN,
+                weight=package.weight.OZ,
+                predefined_package=provider_units.PackagingType.map(
+                    package.packaging_type
+                ).value,
+            ),
+            options={option.code: option.state for _, option in options.items()},
+            customs_info=(
+                easypost.CustomsInfo(
+                    contents_type="other",
+                    customs_certify=True,
+                    customs_signer=shipper.person_name,
+                    customs_items=[
+                        easypost.CustomsItem(
+                            description=lib.text(
+                                item.description or item.title or "N/A"
+                            ),
+                            origin_country=item.origin_country,
+                            quantity=item.quantity,
+                            value=item.value_amount,
+                            weight=units.Weight(item.weight, item.weight_unit).OZ,
+                            code=item.sku,
+                            manufacturer=None,
+                            currency=item.value_currency,
+                            eccn=(item.metadata or {}).get("eccn"),
+                            printed_commodity_identifier=(item.sku or item.id),
+                            hs_tariff_number=item.hs_code,
+                        )
+                        for item in customs.commodities
+                    ],
+                )
+                if customs
+                else None
+            ),
+        )
+    )
+
+    return lib.Serializable(requests, lib.to_dict)

karrio/providers/easypost/shipment/__init__.py

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

karrio/providers/easypost/shipment/cancel.py

@@ -0,0 +1,31 @@
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.easypost.error as provider_error
+import karrio.providers.easypost.units as provider_units
+import karrio.providers.easypost.utils as provider_utils
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    status = response.get("status")
+    errors = provider_error.parse_error_response(response, settings)
+
+    details = models.ConfirmationDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        success=status != "rejected",
+        operation="cancel shipment",
+    )
+
+    return details, errors
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest, _
+) -> lib.Serializable:
+    return lib.Serializable(payload.shipment_identifier)