karrio-eshipper 2025.5__py3-none-any.whl

karrio/providers/eshipper/units.py

@@ -0,0 +1,334 @@
+import typing
+import pathlib
+import karrio.lib as lib
+import karrio.core.units as units
+
+METADATA_JSON = lib.to_dict(
+    lib.load_file_content(
+        pathlib.Path(__file__).resolve().parent / "metadata.json"
+    ).replace('"NULL"', "null")
+)
+KARRIO_CARRIER_MAPPING = {
+    "fed_ex": "fedex",
+    "e_shipper": "eshipper",
+    "tforce_freight": "tforce",
+    "federal_express": "fedex",
+    "canada_post": "canadapost",
+    "e_shipper_ltl": "eshipper",
+    "fedex_freight_ltl": "fedex",
+    "e_shipper_trucking": "eshipper",
+}
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type"""
+
+    Drum = "Drum"
+    Boxes = "Boxes"
+    Rolls = "Rolls"
+    Pipes = "Pipes"
+    Bales = "Bales"
+    Bags = "Bags"
+    Pallet = "Pallet"
+    Cylinder = "Cylinder"
+    Pails = "Pails"
+    Reels = "Reels"
+    Crate = "Crate"
+    Bucket = "Bucket"
+    Bundle = "Bundle"
+    Can = "Can"
+    Carton = "Carton"
+    Case = "Case"
+    Coil = "Coil"
+    Pieces = "Pieces"
+    Skid = "Skid"
+
+    """ Unified Packaging type mapping """
+    tube = Cylinder
+    pallet = Pallet
+    small_box = Boxes
+    medium_box = Boxes
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options"""
+
+    eshipper_signature_required = lib.OptionEnum("signatureRequired", bool)
+    eshipper_insurance_type = lib.OptionEnum("insuranceType")
+    eshipper_dangerous_goods_type = lib.OptionEnum("dangerousGoodsType", bool)
+    eshipper_cod = lib.OptionEnum("cod", float)
+    eshipper_is_saturday_service = lib.OptionEnum("isSaturdayService", bool)
+    eshipper_hold_for_pickup_required = lib.OptionEnum("holdForPickupRequired", bool)
+    eshipper_special_equipment = lib.OptionEnum("specialEquipment", bool)
+    eshipper_inside_delivery = lib.OptionEnum("insideDelivery", bool)
+    eshipper_delivery_appointment = lib.OptionEnum("deliveryAppointment", bool)
+    eshipper_inside_pickup = lib.OptionEnum("insidePickup", bool)
+    eshipper_saturday_pickup_required = lib.OptionEnum("saturdayPickupRequired", bool)
+    eshipper_stackable = lib.OptionEnum("stackable", bool)
+
+    """ Unified Option type mapping """
+    cash_on_delivery = eshipper_cod
+    insurance = eshipper_insurance_type
+    signature_confirmation = eshipper_signature_required
+    saturday_delivery = eshipper_is_saturday_service
+    hold_at_location = eshipper_hold_for_pickup_required
+    dangerous_good = eshipper_dangerous_goods_type
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: units.ShippingOptions = None,
+) -> units.ShippingOptions:
+    """
+    Apply default values to the given options.
+    """
+
+    if package_options is not None:
+        options.update(package_options.content)
+
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption  # type: ignore
+
+    return units.ShippingOptions(options, ShippingOption, items_filter=items_filter)
+
+
+class TrackingStatus(lib.Enum):
+    on_hold = ["on_hold"]
+    delivered = ["delivered"]
+    in_transit = ["in_transit"]
+    delivery_failed = ["delivery_failed"]
+    delivery_delayed = ["delivery_delayed"]
+    out_for_delivery = ["out_for_delivery"]
+    ready_for_pickup = ["ready_for_pickup"]
+
+
+def to_carrier_code(carrierDTO: typing.Dict[str, str]) -> str:
+    _code = lib.to_snake_case((carrierDTO or {}).get("name") or "eshipper")
+
+    # map carrier names to their corresponding Karrio code
+    return KARRIO_CARRIER_MAPPING.get(_code, _code)
+
+
+def to_service_code(service: typing.Dict[str, str]) -> str:
+    parts = list(
+        dict.fromkeys(
+            [
+                to_carrier_code(service.get("carrierDTO")),  # type: ignore
+                *[
+                    _.lower()
+                    for _ in (
+                        service.get("esServicename") or service.get("name")
+                    ).split(" ")
+                ],
+            ][::-1]
+        )
+    )[::-1]
+    output = (
+        lib.to_slug(" ".join(["eshipper", *parts]))
+        .replace("_eshipper", "")
+        .replace("__", "_")
+    )
+
+    return output
+
+
+def get_service(search: str, test_mode: bool = False, service_id: str = None):
+    prod_metadata = METADATA_JSON["PROD_SERVICES"]
+    test_metadata = METADATA_JSON["DEV_SERVICES"]
+    metadata = lib.identity(
+        test_metadata + prod_metadata if test_mode else prod_metadata + test_metadata
+    )
+
+    return next(
+        (
+            service
+            for service in metadata
+            if to_service_code(service) == search
+            or service.get("name") == search
+            or str(service.get("id")) == search
+            or (service_id and service_id == str(service.get("id")))
+        ),
+        {},
+    )
+
+
+def get_service_id(search: str, test_mode: bool = False, service_id: str = None):
+    return (
+        get_service(search, test_mode=test_mode, service_id=service_id).get("id")
+        or service_id
+    )
+
+
+def find_service(search: str, test_mode: bool = False, service_id: str = None):
+
+    if ShippingService.map(search).name:
+        return ShippingService.map(search)
+
+    service = get_service(search, test_mode=test_mode, service_id=service_id)
+
+    if service:
+        return ShippingService.map(to_service_code(service))
+
+    return ShippingService.map(search)
+
+
+def get_carrier(
+    search: str,
+    test_mode: bool = False,
+    service_search: str = None,
+    service_id: str = None,
+):
+    id_key = "test_id" if test_mode else "prod_id"
+    alternate_key = "prod_id" if not test_mode else "test_id"
+    service = get_service(service_search, test_mode=test_mode, service_id=service_id)
+
+    return service.get("carrierDTO") or next(
+        (
+            carrier
+            for carrier in ESHIPPER_CARRIER_METADATA.values()
+            if search == carrier.get(id_key) or search == carrier.get("name")
+        ),
+        next(
+            (
+                carrier
+                for carrier in ESHIPPER_CARRIER_METADATA.values()
+                if search == carrier.get(alternate_key) or search == carrier.get("name")
+            ),
+            {},
+        ),
+    )
+
+
+def get_carrier_id(
+    search: str,
+    test_mode: bool = False,
+    service_search: str = None,
+    service_id: str = None,
+):
+    return get_carrier(
+        search,
+        test_mode=test_mode,
+        service_search=service_search,
+        service_id=service_id,
+    ).get("id")
+
+
+def find_rate_provider(
+    search: str,
+    test_mode: bool = False,
+    service_search: str = None,
+    service_id: str = None,
+):
+
+    if RateProvider.map(lib.to_snake_case(search)).name:
+        return RateProvider.map(lib.to_snake_case(search))
+
+    carrier = get_carrier(
+        search,
+        test_mode=test_mode,
+        service_search=service_search,
+        service_id=service_id,
+    )
+
+    if carrier and RateProvider.map(to_carrier_code(carrier)).name:
+        return RateProvider.map(to_carrier_code(carrier))
+
+    return RateProvider.map(lib.to_snake_case(search))
+
+
+ESHIPPER_CARRIER_METADATA = {
+    lib.to_snake_case(carrier["carrierDTO"]["name"]): {
+        **carrier["carrierDTO"],
+        "ids": list(
+            set(
+                [
+                    s["carrierDTO"]["id"]
+                    for s in METADATA_JSON["PROD_SERVICES"]
+                    + METADATA_JSON["DEV_SERVICES"]
+                    if s["carrierDTO"]["name"] == carrier["carrierDTO"]["name"]
+                ]
+            )
+        ),
+        "prod_id": next(
+            (
+                s["carrierDTO"]["id"]
+                for s in METADATA_JSON["PROD_SERVICES"]
+                if s["carrierDTO"]["name"] == carrier["carrierDTO"]["name"]
+            ),
+            None,
+        ),
+        "test_id": next(
+            (
+                s["carrierDTO"]["id"]
+                for s in METADATA_JSON["DEV_SERVICES"]
+                if s["carrierDTO"]["name"] == carrier["carrierDTO"]["name"]
+            ),
+            None,
+        ),
+    }
+    for carrier in {
+        s["carrierDTO"]["name"]: s
+        for s in METADATA_JSON["PROD_SERVICES"] + METADATA_JSON["DEV_SERVICES"]
+    }.values()
+}
+
+ESHIPPER_SERVICE_METADATA = {
+    lib.to_snake_case(service.get("esServicename") or service.get("name")): {
+        **service,
+        "ids": list(
+            set(
+                [
+                    s["id"]
+                    for s in METADATA_JSON["PROD_SERVICES"]
+                    + METADATA_JSON["DEV_SERVICES"]
+                    if lib.to_snake_case(s["name"])
+                    == lib.to_snake_case(service["name"])
+                ]
+            )
+        ),
+        "prod_id": next(
+            (
+                s["id"]
+                for s in METADATA_JSON["PROD_SERVICES"]
+                if s["name"] == service["name"]
+            ),
+            None,
+        ),
+        "test_id": next(
+            (
+                s["id"]
+                for s in METADATA_JSON["DEV_SERVICES"]
+                if s["name"] == service["name"]
+            ),
+            None,
+        ),
+        "carrier": lib.to_snake_case(service["carrierDTO"]["name"]),
+    }
+    for service in {
+        s["name"]: s
+        for s in METADATA_JSON["PROD_SERVICES"] + METADATA_JSON["DEV_SERVICES"]
+    }.values()
+}
+
+
+ShippingService = lib.StrEnum(
+    "ShippingService",
+    {
+        to_service_code(service): service["name"]
+        for service in ESHIPPER_SERVICE_METADATA.values()
+    },
+)
+
+RateProvider = lib.StrEnum(
+    "RateProvider",
+    {
+        to_carrier_code(carrier): slug
+        for slug, carrier in ESHIPPER_CARRIER_METADATA.items()
+    },
+)
+
+
+setattr(ShippingService, "service_id", get_service_id)
+setattr(ShippingService, "carrier_id", get_carrier_id)
+setattr(ShippingService, "find", find_service)
+setattr(RateProvider, "find", find_rate_provider)

karrio/providers/eshipper/utils.py

@@ -0,0 +1,76 @@
+import datetime
+import karrio.lib as lib
+import karrio.core as core
+import karrio.core.errors as errors
+
+
+class Settings(core.Settings):
+    """eShipper connection settings."""
+
+    principal: str
+    credential: str
+
+    @property
+    def carrier_name(self):
+        return "eshipper"
+
+    @property
+    def server_url(self):
+        return (
+            "https://uu2.eshipper.com" if self.test_mode else "https://ww2.eshipper.com"
+        )
+
+    @property
+    def access_token(self):
+        """Retrieve the "token" using the principal|credential pair
+        or collect it from the cache if an unexpired "token" exist.
+        """
+        cache_key = f"{self.carrier_name}|{self.principal}|{self.credential}"
+        now = datetime.datetime.now() + datetime.timedelta(minutes=30)
+
+        auth = self.connection_cache.get(cache_key) or {}
+        token = auth.get("token")
+        expiry = lib.to_date(auth.get("expiry"), current_format="%Y-%m-%d %H:%M:%S")
+
+        if token is not None and expiry is not None and expiry > now:
+            return token
+
+        self.connection_cache.set(cache_key, lambda: login(self))
+        new_auth = self.connection_cache.get(cache_key)
+
+        return new_auth["token"]
+
+
+def login(settings: Settings):
+    """Sign in response
+    {
+      "token": "string",
+      "expires_in": "string",
+      "token_type": "string",
+      "refresh_token": "string",
+      "refresh_expires_in": "string"
+    }
+    """
+    import karrio.providers.eshipper.error as error
+
+    result = lib.request(
+        url=f"{settings.server_url}/api/v2/authenticate",
+        data=lib.to_json(
+            {
+                "principal": settings.principal,
+                "credential": settings.credential,
+            }
+        ),
+        method="POST",
+        headers={"content-Type": "application/json"},
+    )
+    response = lib.to_dict(result)
+    messages = error.parse_error_response(response, settings)
+
+    if any(messages):
+        raise errors.ParsedMessagesError(messages=messages)
+
+    expiry = datetime.datetime.now() + datetime.timedelta(
+        seconds=float(response.get("expires_in", 0))
+    )
+    return {**response, "expiry": lib.fdatetime(expiry)}

karrio/schemas/eshipper/cancel_request.py

@@ -0,0 +1,15 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class OrderType:
+    trackingId: typing.Optional[str] = None
+    orderId: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CancelRequestType:
+    order: typing.Optional[OrderType] = jstruct.JStruct[OrderType]

karrio/schemas/eshipper/cancel_response.py

@@ -0,0 +1,15 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class OrderType:
+    trackingId: typing.Optional[str] = None
+    orderId: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CancelResponseType:
+    order: typing.Optional[typing.List[OrderType]] = jstruct.JList[OrderType]

karrio/schemas/eshipper/error_response.py

@@ -0,0 +1,21 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class FieldErrorType:
+    objectName: typing.Optional[str] = None
+    field: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ErrorResponseType:
+    status: typing.Optional[int] = None
+    title: typing.Optional[str] = None
+    type: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+    code: typing.Optional[str] = None
+    fieldErrors: typing.Optional[typing.List[FieldErrorType]] = jstruct.JList[FieldErrorType]
+    thirdPartyMessage: typing.Optional[str] = None

karrio/schemas/eshipper/pickup_cancel_response.py

@@ -0,0 +1,9 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class PickupCancelResponseType:
+    orderId: typing.Optional[int] = None
+    status: typing.Optional[str] = None

karrio/schemas/eshipper/pickup_request.py

@@ -0,0 +1,25 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class TimeType:
+    hour: typing.Optional[int] = None
+    minute: typing.Optional[int] = None
+    second: typing.Optional[int] = None
+    nano: typing.Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupRequestType:
+    contactName: typing.Optional[str] = None
+    phoneNumber: typing.Optional[str] = None
+    pickupDate: typing.Optional[str] = None
+    pickupTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    closingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletPickupTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletClosingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletDeliveryClosingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    location: typing.Optional[str] = None
+    instructions: typing.Optional[str] = None

karrio/schemas/eshipper/pickup_response.py

@@ -0,0 +1,16 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class OrderType:
+    trackingId: typing.Optional[str] = None
+    orderId: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupResponseType:
+    order: typing.Optional[OrderType] = jstruct.JStruct[OrderType]
+    message: typing.Optional[str] = None

karrio/schemas/eshipper/rate_request.py

@@ -0,0 +1,181 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class CodAddressType:
+    company: typing.Optional[str] = None
+    name: typing.Optional[str] = None
+    addressLine1: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    province: typing.Optional[str] = None
+    country: typing.Optional[str] = None
+    zip: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CodType:
+    codAddress: typing.Optional[CodAddressType] = jstruct.JStruct[CodAddressType]
+    paymentType: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class BillingAddressType:
+    company: typing.Optional[str] = None
+    attention: typing.Optional[str] = None
+    address1: typing.Optional[str] = None
+    address2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    province: typing.Optional[str] = None
+    country: typing.Optional[str] = None
+    zip: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ContactType:
+    contactCompany: typing.Optional[str] = None
+    contactName: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    brokerName: typing.Optional[str] = None
+    brokerTaxId: typing.Optional[str] = None
+    recipientTaxId: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class DutiesTaxesType:
+    dutiable: typing.Optional[bool] = None
+    billTo: typing.Optional[str] = None
+    accountNumber: typing.Optional[str] = None
+    sedNumber: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ItemType:
+    hsnCode: typing.Optional[str] = None
+    description: typing.Optional[str] = None
+    originCountry: typing.Optional[str] = None
+    quantity: typing.Optional[int] = None
+    unitPrice: typing.Optional[int] = None
+    skuCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ItemsType:
+    item: typing.Optional[typing.List[ItemType]] = jstruct.JList[ItemType]
+    currency: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CustomsInformationType:
+    contact: typing.Optional[ContactType] = jstruct.JStruct[ContactType]
+    items: typing.Optional[ItemsType] = jstruct.JStruct[ItemsType]
+    dutiesTaxes: typing.Optional[DutiesTaxesType] = jstruct.JStruct[DutiesTaxesType]
+    billingAddress: typing.Optional[BillingAddressType] = jstruct.JStruct[BillingAddressType]
+    remarks: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PackageType:
+    height: typing.Optional[int] = None
+    length: typing.Optional[int] = None
+    width: typing.Optional[int] = None
+    dimensionUnit: typing.Optional[str] = None
+    weight: typing.Optional[int] = None
+    weightUnit: typing.Optional[str] = None
+    type: typing.Optional[str] = None
+    freightClass: typing.Optional[str] = None
+    nmfcCode: typing.Optional[str] = None
+    insuranceAmount: typing.Optional[int] = None
+    codAmount: typing.Optional[int] = None
+    description: typing.Optional[str] = None
+    harmonizedCode: typing.Optional[str] = None
+    skuCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PackagesType:
+    type: typing.Optional[str] = None
+    packages: typing.Optional[typing.List[PackageType]] = jstruct.JList[PackageType]
+
+
+@attr.s(auto_attribs=True)
+class TimeType:
+    hour: typing.Optional[int] = None
+    minute: typing.Optional[int] = None
+    second: typing.Optional[int] = None
+    nano: typing.Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupType:
+    contactName: typing.Optional[str] = None
+    phoneNumber: typing.Optional[str] = None
+    pickupDate: typing.Optional[str] = None
+    pickupTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    closingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletPickupTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletClosingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    palletDeliveryClosingTime: typing.Optional[TimeType] = jstruct.JStruct[TimeType]
+    location: typing.Optional[str] = None
+    instructions: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class FromType:
+    attention: typing.Optional[str] = None
+    company: typing.Optional[str] = None
+    address1: typing.Optional[str] = None
+    address2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    province: typing.Optional[str] = None
+    country: typing.Optional[str] = None
+    zip: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    instructions: typing.Optional[str] = None
+    residential: typing.Optional[bool] = None
+    tailgateRequired: typing.Optional[bool] = None
+    confirmDelivery: typing.Optional[bool] = None
+    notifyRecipient: typing.Optional[bool] = None
+
+
+@attr.s(auto_attribs=True)
+class ThirdPartyBillingType:
+    carrier: typing.Optional[int] = None
+    country: typing.Optional[int] = None
+    billToAccountNumber: typing.Optional[str] = None
+    billToPostalCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class RateRequestType:
+    scheduledShipDate: typing.Optional[str] = None
+    raterequestfrom: typing.Optional[FromType] = jstruct.JStruct[FromType]
+    to: typing.Optional[FromType] = jstruct.JStruct[FromType]
+    packagingUnit: typing.Optional[str] = None
+    packages: typing.Optional[PackagesType] = jstruct.JStruct[PackagesType]
+    reference1: typing.Optional[str] = None
+    reference2: typing.Optional[str] = None
+    reference3: typing.Optional[str] = None
+    transactionId: typing.Optional[str] = None
+    signatureRequired: typing.Optional[str] = None
+    insuranceType: typing.Optional[str] = None
+    dangerousGoodsType: typing.Optional[str] = None
+    pickup: typing.Optional[PickupType] = jstruct.JStruct[PickupType]
+    customsInformation: typing.Optional[CustomsInformationType] = jstruct.JStruct[CustomsInformationType]
+    customsInBondFreight: typing.Optional[bool] = None
+    cod: typing.Optional[CodType] = jstruct.JStruct[CodType]
+    isSaturdayService: typing.Optional[bool] = None
+    holdForPickupRequired: typing.Optional[bool] = None
+    specialEquipment: typing.Optional[bool] = None
+    insideDelivery: typing.Optional[bool] = None
+    deliveryAppointment: typing.Optional[bool] = None
+    insidePickup: typing.Optional[bool] = None
+    saturdayPickupRequired: typing.Optional[bool] = None
+    stackable: typing.Optional[bool] = None
+    serviceId: typing.Optional[int] = None
+    thirdPartyBilling: typing.Optional[ThirdPartyBillingType] = jstruct.JStruct[ThirdPartyBillingType]
+    commodityType: typing.Optional[str] = None