karrio-freightcom 2025.5.6__py3-none-any.whl

karrio/mappers/freightcom/__init__.py

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

karrio/mappers/freightcom/mapper.py

@@ -0,0 +1,55 @@
+from typing import List, Tuple
+from karrio.api.mapper import Mapper as BaseMapper
+from karrio.mappers.freightcom.settings import Settings
+from karrio.core.utils.serializable import Deserializable, Serializable
+from karrio.core.models import (
+    RateRequest,
+    ShipmentRequest,
+    ShipmentDetails,
+    RateDetails,
+    Message,
+    ShipmentCancelRequest,
+    ConfirmationDetails,
+)
+from karrio.providers.freightcom import (
+    parse_quote_reply,
+    quote_request,
+    parse_shipping_reply,
+    shipping_request,
+    shipment_cancel_request,
+    parse_shipment_cancel_reply,
+)
+
+
+class Mapper(BaseMapper):
+    settings: Settings
+
+    # Request Mappers
+
+    def create_rate_request(self, payload: RateRequest) -> Serializable:
+        return quote_request(payload, self.settings)
+
+    def create_shipment_request(self, payload: ShipmentRequest) -> Serializable:
+        return shipping_request(payload, self.settings)
+
+    def create_cancel_shipment_request(
+        self, payload: ShipmentCancelRequest
+    ) -> Serializable:
+        return shipment_cancel_request(payload, self.settings)
+
+    # Response Parsers
+
+    def parse_rate_response(
+        self, response: Deserializable
+    ) -> Tuple[List[RateDetails], List[Message]]:
+        return parse_quote_reply(response, self.settings)
+
+    def parse_shipment_response(
+        self, response: Deserializable
+    ) -> Tuple[ShipmentDetails, List[Message]]:
+        return parse_shipping_reply(response, self.settings)
+
+    def parse_cancel_shipment_response(
+        self, response: Deserializable
+    ) -> Tuple[ConfirmationDetails, List[Message]]:
+        return parse_shipment_cancel_reply(response, self.settings)

karrio/mappers/freightcom/proxy.py

@@ -0,0 +1,38 @@
+from karrio.core.utils import request as http, XP
+from karrio.api.proxy import Proxy as BaseProxy
+from karrio.mappers.freightcom.settings import Settings
+from karrio.core.utils.serializable import Serializable, Deserializable
+
+
+class Proxy(BaseProxy):
+    settings: Settings
+
+    def get_rates(self, request: Serializable) -> Deserializable:
+        response = http(
+            url=self.settings.server_url,
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={"Content-Type": "application/xml"},
+        )
+        return Deserializable(response, XP.to_xml)
+
+    def create_shipment(self, request: Serializable) -> Deserializable:
+        response = http(
+            url=self.settings.server_url,
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={"Content-Type": "application/xml"},
+        )
+        return Deserializable(response, XP.to_xml)
+
+    def cancel_shipment(self, request: Serializable) -> Deserializable:
+        response = http(
+            url=self.settings.server_url,
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={"Content-Type": "application/xml"},
+        )
+        return Deserializable(response, XP.to_xml)

karrio/mappers/freightcom/settings.py

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

karrio/plugins/freightcom/__init__.py

@@ -0,0 +1,19 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.freightcom as mappers
+import karrio.providers.freightcom.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="deprecated",
+    id="freightcom",
+    label="Freightcom",
+    is_hub=True,
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    hub_carriers=units.CARRIER_IDS,
+)

karrio/providers/freightcom/__init__.py

@@ -0,0 +1,6 @@
+from karrio.providers.freightcom.quote import parse_quote_reply, quote_request
+from karrio.providers.freightcom.shipping import (
+    parse_shipping_reply,
+    shipping_request,
+)
+from karrio.providers.freightcom.void_shipment import shipment_cancel_request, parse_shipment_cancel_reply

karrio/providers/freightcom/error.py

@@ -0,0 +1,40 @@
+from typing import List
+from karrio.schemas.freightcom.error import ErrorType
+from karrio.schemas.freightcom.quote_reply import CarrierErrorMessageType
+from karrio.core.models import Message
+from karrio.core.utils import Element, XP
+from karrio.providers.freightcom.utils import Settings
+
+
+def parse_error_response(response: Element, settings: Settings) -> List[Message]:
+    errors = XP.find("Error", response, ErrorType)
+    carrier_errors = XP.find("CarrierErrorMessage", response, CarrierErrorMessageType)
+
+    return [
+        *[_extract_error(er, settings) for er in errors if er.Message != ""],
+        *[
+            _extract_carrier_error(er, settings)
+            for er in carrier_errors
+            if er.errorMessage0 != ""
+        ],
+    ]
+
+
+def _extract_carrier_error(
+    error: CarrierErrorMessageType, settings: Settings
+) -> Message:
+    return Message(
+        code="CarrierErrorMessage",
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        message=error.errorMessage0,
+    )
+
+
+def _extract_error(error: ErrorType, settings: Settings) -> Message:
+    return Message(
+        code="Error",
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        message=error.Message,
+    )

karrio/providers/freightcom/quote.py

@@ -0,0 +1,179 @@
+from karrio.schemas.freightcom.quote_request import (
+    Freightcom,
+    QuoteRequestType,
+    FromType,
+    ToType,
+    PackagesType,
+    PackageType,
+)
+from karrio.schemas.freightcom.quote_reply import QuoteType
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.freightcom.error as provider_error
+import karrio.providers.freightcom.units as provider_units
+import karrio.providers.freightcom.utils as provider_utils
+
+
+def parse_quote_reply(
+    _response: lib.Deserializable[lib.Element], settings: provider_utils.Settings
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    estimates = lib.find_element("Quote", response)
+
+    return (
+        [_extract_rate(node, settings) for node in estimates],
+        provider_error.parse_error_response(response, settings),
+    )
+
+
+def _extract_rate(
+    node: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.RateDetails:
+    quote = lib.to_object(QuoteType, node)
+    rate_provider, service, service_name = provider_units.ShippingService.info(
+        quote.serviceId,
+        quote.carrierId,
+        quote.serviceName,
+        quote.carrierName,
+    )
+    charges = [
+        ("Base charge", quote.baseCharge),
+        ("Fuel surcharge", quote.fuelSurcharge),
+        *((surcharge.name, surcharge.amount) for surcharge in quote.Surcharge),
+    ]
+
+    return models.RateDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        currency=quote.currency,
+        service=service,
+        total_charge=lib.to_decimal(quote.totalCharge),
+        transit_days=quote.transitDays,
+        extra_charges=[
+            models.ChargeDetails(
+                name=name,
+                currency="CAD",
+                amount=lib.to_decimal(amount),
+            )
+            for name, amount in charges
+            if amount
+        ],
+        meta=dict(rate_provider=rate_provider, service_name=service_name),
+    )
+
+
+def quote_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(
+        payload.parcels,
+        package_option_type=provider_units.ShippingOption,
+        required=["weight", "height", "width", "length"],
+    )
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    packaging_type = provider_units.FreightPackagingType[
+        packages.package_type or "small_box"
+    ].value
+    packaging = (
+        "Pallet"
+        if packaging_type in [provider_units.FreightPackagingType.pallet.value]
+        else "Package"
+    )
+    service = (
+        lib.to_services(payload.services, provider_units.ShippingService).first
+        or provider_units.ShippingService.freightcom_all
+    )
+
+    request = Freightcom(
+        username=settings.username,
+        password=settings.password,
+        version="3.1.0",
+        QuoteRequest=QuoteRequestType(
+            saturdayPickupRequired=options.freightcom_saturday_pickup_required.state,
+            homelandSecurity=options.freightcom_homeland_security.state,
+            pierCharge=None,
+            exhibitionConventionSite=options.freightcom_exhibition_convention_site.state,
+            militaryBaseDelivery=options.freightcom_military_base_delivery.state,
+            customsIn_bondFreight=options.freightcom_customs_in_bond_freight.state,
+            limitedAccess=options.freightcom_limited_access.state,
+            excessLength=options.freightcom_excess_length.state,
+            tailgatePickup=options.freightcom_tailgate_pickup.state,
+            residentialPickup=options.freightcom_residential_pickup.state,
+            crossBorderFee=None,
+            notifyRecipient=options.freightcom_notify_recipient.state,
+            singleShipment=options.freightcom_single_shipment.state,
+            tailgateDelivery=options.freightcom_tailgate_delivery.state,
+            residentialDelivery=options.freightcom_residential_delivery.state,
+            insuranceType=options.insurance.state is not None,
+            scheduledShipDate=None,
+            insideDelivery=options.freightcom_inside_delivery.state,
+            isSaturdayService=options.freightcom_is_saturday_service.state,
+            dangerousGoodsType=options.freightcom_dangerous_goods_type.state,
+            serviceId=service.value,
+            stackable=options.freightcom_stackable.state,
+            From=FromType(
+                id=None,
+                company=shipper.company_name or " ",
+                instructions=None,
+                email=shipper.email,
+                attention=shipper.person_name,
+                phone=shipper.phone_number,
+                tailgateRequired=None,
+                residential=shipper.residential,
+                address1=shipper.street,
+                address2=lib.text(shipper.address_line2),
+                city=shipper.city,
+                state=shipper.state_code,
+                zip=shipper.postal_code,
+                country=shipper.country_code,
+            ),
+            To=ToType(
+                id=None,
+                company=recipient.company_name or " ",
+                notifyRecipient=None,
+                instructions=None,
+                email=recipient.email,
+                attention=recipient.person_name,
+                phone=recipient.phone_number,
+                tailgateRequired=None,
+                residential=recipient.residential,
+                address1=recipient.street,
+                address2=lib.text(recipient.address_line2),
+                city=recipient.city,
+                state=recipient.state_code,
+                zip=recipient.postal_code,
+                country=recipient.country_code,
+            ),
+            COD=None,
+            Packages=PackagesType(
+                Package=[
+                    PackageType(
+                        length=provider_utils.ceil(package.length.IN),
+                        width=provider_utils.ceil(package.width.IN),
+                        height=provider_utils.ceil(package.height.IN),
+                        weight=provider_utils.ceil(package.weight.LB),
+                        type_=packaging_type,
+                        freightClass=package.parcel.freight_class,
+                        nmfcCode=None,
+                        insuranceAmount=package.options.insurance.state,
+                        codAmount=package.options.cash_on_delivery.state,
+                        description=package.parcel.description,
+                    )
+                    for package in packages
+                ],
+                type_=packaging,
+            ),
+        ),
+    )
+
+    return lib.Serializable(request, provider_utils.standard_request_serializer)

karrio/providers/freightcom/shipping.py

@@ -0,0 +1,294 @@
+from karrio.schemas.freightcom.shipping_request import (
+    Freightcom,
+    ShippingRequestType,
+    FromType,
+    ToType,
+    PackagesType,
+    PackageType,
+    PaymentType as RequestPaymentType,
+    CODType,
+    CODReturnAddressType,
+    ContactType,
+    ReferenceType,
+    CustomsInvoiceType,
+    ItemType,
+    BillToType,
+)
+from karrio.schemas.freightcom.shipping_reply import (
+    ShippingReplyType,
+    QuoteType,
+)
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.freightcom.error as provider_error
+import karrio.providers.freightcom.units as provider_units
+import karrio.providers.freightcom.utils as provider_utils
+
+
+def parse_shipping_reply(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    shipping_node = lib.find_element("ShippingReply", response, first=True)
+    shipment = (
+        _extract_shipment(shipping_node, settings)
+        if shipping_node is not None
+        else None
+    )
+
+    return shipment, provider_error.parse_error_response(response, settings)
+
+
+def _extract_shipment(
+    node: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    shipping = lib.to_object(ShippingReplyType, node)
+    quote: QuoteType = shipping.Quote or QuoteType()
+
+    tracking_number = getattr(
+        next(iter(shipping.Package), None), "trackingNumber", None
+    )
+    rate_provider, service, service_name = provider_units.ShippingService.info(
+        quote.serviceId, quote.carrierId, quote.serviceName, quote.carrierName
+    )
+    invoice = dict(invoice=shipping.CustomsInvoice) if shipping.CustomsInvoice else {}
+    charges = [
+        ("Base charge", quote.baseCharge),
+        ("Fuel surcharge", quote.fuelSurcharge),
+        *((surcharge.name, surcharge.amount) for surcharge in quote.Surcharge),
+    ]
+
+    return models.ShipmentDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=tracking_number,
+        shipment_identifier=shipping.Order.id,
+        selected_rate=(
+            models.RateDetails(
+                carrier_name=settings.carrier_name,
+                carrier_id=settings.carrier_id,
+                service=service,
+                currency=quote.currency,
+                total_charge=lib.to_decimal(quote.totalCharge),
+                transit_days=quote.transitDays,
+                extra_charges=[
+                    models.ChargeDetails(
+                        name=name,
+                        currency="CAD",
+                        amount=lib.to_decimal(amount),
+                    )
+                    for name, amount in charges
+                    if amount
+                ],
+                meta=dict(rate_provider=rate_provider, service_name=service_name),
+            )
+            if shipping.Quote is not None
+            else None
+        ),
+        docs=models.Documents(label=shipping.Labels, **invoice),
+        meta=dict(
+            rate_provider=rate_provider,
+            service_name=service_name,
+            tracking_url=shipping.TrackingURL,
+        ),
+    )
+
+
+def shipping_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    service = provider_units.ShippingService.map(payload.service).value_or_key
+    packages = lib.to_packages(
+        payload.parcels,
+        package_option_type=provider_units.ShippingOption,
+        required=["weight", "height", "width", "length"],
+    )
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    is_intl = shipper.country_code != recipient.country_code
+    customs = lib.to_customs_info(
+        payload.customs,
+        shipper=payload.shipper,
+        recipient=payload.recipient,
+        weight_unit=packages.weight_unit,
+        default_to=(
+            models.Customs(
+                commodities=(
+                    packages.items
+                    if any(packages.items)
+                    else [
+                        models.Commodity(
+                            quantity=1,
+                            sku=f"000{index}",
+                            weight=pkg.weight.value,
+                            weight_unit=pkg.weight_unit.value,
+                            description=pkg.parcel.content,
+                        )
+                        for index, pkg in enumerate(packages, start=1)
+                    ]
+                )
+            )
+            if is_intl
+            else None
+        ),
+    )
+
+    packaging_type = provider_units.FreightPackagingType.map(
+        packages.package_type or "small_box"
+    ).value
+    packaging = (
+        "Pallet"
+        if packaging_type in [provider_units.FreightPackagingType.pallet.value]
+        else "Package"
+    )
+    payment = payload.payment or models.Payment()
+    payment_type = (
+        provider_units.PaymentType[payment.paid_by] if payload.payment else None
+    )
+
+    request = Freightcom(
+        version="3.1.0",
+        username=settings.username,
+        password=settings.password,
+        ShippingRequest=ShippingRequestType(
+            saturdayPickupRequired=options.freightcom_saturday_pickup_required.state,
+            homelandSecurity=options.freightcom_homeland_security.state,
+            pierCharge=None,
+            exhibitionConventionSite=options.freightcom_exhibition_convention_site.state,
+            militaryBaseDelivery=options.freightcom_military_base_delivery.state,
+            customsIn_bondFreight=options.freightcom_customs_in_bond_freight.state,
+            limitedAccess=options.freightcom_limited_access.state,
+            excessLength=options.freightcom_excess_length.state,
+            tailgatePickup=options.freightcom_tailgate_pickup.state,
+            residentialPickup=options.freightcom_residential_pickup.state,
+            crossBorderFee=None,
+            notifyRecipient=options.freightcom_notify_recipient.state,
+            singleShipment=options.freightcom_single_shipment.state,
+            tailgateDelivery=options.freightcom_tailgate_delivery.state,
+            residentialDelivery=options.freightcom_residential_delivery.state,
+            insuranceType=(options.insurance.state is not None),
+            scheduledShipDate=None,
+            insideDelivery=options.freightcom_inside_delivery.state,
+            isSaturdayService=options.freightcom_is_saturday_service.state,
+            dangerousGoodsType=options.freightcom_dangerous_goods_type.state,
+            serviceId=service,
+            stackable=options.freightcom_stackable.state,
+            From=FromType(
+                id=None,
+                company=shipper.company_name,
+                instructions=None,
+                email=shipper.email,
+                attention=shipper.person_name,
+                phone=shipper.phone_number,
+                tailgateRequired=None,
+                residential=shipper.residential,
+                address1=shipper.street,
+                address2=lib.text(shipper.address_line2),
+                city=shipper.city,
+                state=shipper.state_code,
+                zip=shipper.postal_code,
+                country=shipper.country_code,
+            ),
+            To=ToType(
+                id=None,
+                company=recipient.company_name,
+                notifyRecipient=None,
+                instructions=None,
+                email=recipient.email,
+                attention=recipient.person_name,
+                phone=recipient.phone_number,
+                tailgateRequired=None,
+                residential=recipient.residential,
+                address1=recipient.street,
+                address2=lib.text(recipient.address_line2),
+                city=recipient.city,
+                state=recipient.state_code,
+                zip=recipient.postal_code,
+                country=recipient.country_code,
+            ),
+            COD=(
+                CODType(
+                    paymentType=provider_units.PaymentType.recipient.value,
+                    CODReturnAddress=CODReturnAddressType(
+                        codCompany=recipient.company_name,
+                        codName=recipient.person_name,
+                        codAddress1=lib.text(recipient.address_line1),
+                        codCity=recipient.city,
+                        codStateCode=recipient.state_code,
+                        codZip=recipient.postal_code,
+                        codCountry=recipient.country_code,
+                    ),
+                )
+                if options.cash_on_delivery.state is not None
+                else None
+            ),
+            Packages=PackagesType(
+                Package=[
+                    PackageType(
+                        length=provider_utils.ceil(package.length.IN),
+                        width=provider_utils.ceil(package.width.IN),
+                        height=provider_utils.ceil(package.height.IN),
+                        weight=provider_utils.ceil(package.weight.LB),
+                        type_=packaging_type,
+                        freightClass=package.parcel.freight_class,
+                        nmfcCode=None,
+                        insuranceAmount=package.options.insurance.state,
+                        codAmount=package.options.cash_on_delivery.state,
+                        description=package.parcel.description,
+                    )
+                    for package in packages
+                ],
+                type_=packaging,
+            ),
+            Payment=(RequestPaymentType(type_=payment_type) if payment_type else None),
+            Reference=(
+                [ReferenceType(name="REF", code=payload.reference)]
+                if payload.reference != ""
+                else None
+            ),
+            CustomsInvoice=(
+                CustomsInvoiceType(
+                    BillTo=BillToType(
+                        company=customs.duty_billing_address.company_name,
+                        name=customs.duty_billing_address.person_name,
+                        address1=customs.duty_billing_address.address_line,
+                        city=customs.duty_billing_address.city,
+                        state=customs.duty_billing_address.state_code,
+                        zip=customs.duty_billing_address.postal_code,
+                        country=customs.duty_billing_address.country_code,
+                    ),
+                    Contact=ContactType(
+                        name=customs.duty_billing_address.person_name,
+                        phone=customs.duty_billing_address.phone_number,
+                    ),
+                    Item=[
+                        ItemType(
+                            code=(item.hs_code or item.sku or "0000"),
+                            description=lib.text(
+                                item.description or item.title or "item"
+                            ),
+                            originCountry=(item.origin_country or shipper.country_code),
+                            unitPrice=item.value_amount,
+                            quantity=(item.quantity or 1),
+                        )
+                        for item in customs.commodities
+                    ],
+                )
+                if payload.customs
+                else None
+            ),
+        ),
+    )
+
+    return lib.Serializable(request, provider_utils.standard_request_serializer)