karrio-eshipper 2025.5__py3-none-any.whl

karrio/providers/eshipper/rate.py

@@ -0,0 +1,197 @@
+import karrio.schemas.eshipper.rate_request as eshipper
+import karrio.schemas.eshipper.rate_response as rating
+import typing
+import datetime
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.eshipper.error as error
+import karrio.providers.eshipper.utils as provider_utils
+import karrio.providers.eshipper.units as provider_units
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    rates = [_extract_details(rate, settings) for rate in response.get("quotes", [])]
+
+    return rates, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.RateDetails:
+    rate = lib.to_object(rating.QuoteType, data)
+    service = provider_units.ShippingService.find(
+        rate.serviceName,
+        service_id=rate.serviceId,
+        test_mode=settings.test_mode,
+    )
+    carrier_id = provider_units.ShippingService.carrier_id(
+        rate.carrierName,
+        test_mode=settings.test_mode,
+        service_search=service.name_or_key,
+        service_id=rate.serviceId,
+    )
+    rate_provider = provider_units.RateProvider.find(
+        rate.carrierName,
+        test_mode=settings.test_mode,
+        service_search=service.name_or_key,
+        service_id=rate.serviceId,
+    )
+
+    charges = [
+        ("baseCharge", rate.baseCharge),
+        ("fuelSurcharge", rate.fuelSurcharge),
+        ("carbonNeutralFees", rate.carbonNeutralFees),
+        ("processingFees", rate.processingFees),
+        ("totalChargedAmount", rate.totalChargedAmount),
+        *((_.name, _.amount) for _ in rate.surcharges),
+        *((_.name, _.amount) for _ in rate.taxes),
+    ]
+
+    return models.RateDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        service=service.name_or_key,
+        total_charge=lib.to_money(rate.totalCharge),
+        currency=rate.currency,
+        transit_days=lib.to_int(rate.transitDays),
+        extra_charges=[
+            models.ChargeDetails(
+                name=name,
+                currency=rate.currency,
+                amount=lib.to_money(amount),
+            )
+            for name, amount in charges
+            if amount
+        ],
+        meta=dict(
+            eshipper_carrier_id=carrier_id,
+            eshipper_service_id=rate.serviceId,
+            eshipper_carrier_name=rate.carrierName,
+            eshipper_service_name=rate.serviceName,
+            rate_provider=rate_provider.name_or_key,
+            service_name=service.name or rate.serviceName,
+        ),
+    )
+
+
+def rate_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)
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+    )
+    services = lib.to_services(payload.services, provider_units.ShippingService)
+    print(services, "<<<")
+    service_id = lib.identity(
+        options.eshipper_service_id.state
+        or provider_units.ShippingService.service_id(
+            services.first,
+            test_mode=settings.test_mode,
+        )
+    )
+
+    request = eshipper.RateRequestType(
+        scheduledShipDate=lib.fdatetime(
+            lib.to_next_business_datetime(
+                options.shipping_date.state or datetime.datetime.now(),
+                current_format="%Y-%m-%dT%H:%M",
+            ),
+            output_format="%Y-%m-%d %H:%M",
+        ),
+        raterequestfrom=eshipper.FromType(
+            attention=shipper.contact,
+            company=shipper.company_name,
+            address1=shipper.address_line1,
+            address2=shipper.address_line2,
+            city=shipper.city,
+            province=shipper.state_code,
+            country=shipper.country_code,
+            zip=shipper.postal_code,
+            email=shipper.email_address,
+            phone=shipper.phone_number,
+            instructions=None,
+            residential=shipper.is_residential,
+            tailgateRequired=None,
+            confirmDelivery=None,
+            notifyRecipient=None,
+        ),
+        to=eshipper.FromType(
+            attention=recipient.contact,
+            company=recipient.company_name,
+            address1=recipient.address_line1,
+            address2=recipient.address_line2,
+            city=recipient.city,
+            province=recipient.state_code,
+            country=recipient.country_code,
+            zip=recipient.postal_code,
+            email=recipient.email_address,
+            phone=recipient.phone_number,
+            instructions=None,
+            residential=recipient.is_residential,
+            tailgateRequired=None,
+            confirmDelivery=None,
+            notifyRecipient=None,
+        ),
+        packagingUnit="Metric" if packages.weight_unit.lower() == "kg" else "Imperial",
+        packages=eshipper.PackagesType(
+            type="Package",
+            packages=[
+                eshipper.PackageType(
+                    height=lib.to_int(package.height.value),
+                    length=lib.to_int(package.length.value),
+                    width=lib.to_int(package.width.value),
+                    weight=lib.to_int(package.weight.value),
+                    dimensionUnit=package.dimension_unit.value,
+                    weightUnit=package.weight_unit.value,
+                    type=provider_units.PackagingType.map(package.packaging_type).value,
+                    freightClass=None,
+                    nmfcCode=None,
+                    insuranceAmount=None,
+                    codAmount=None,
+                    description=package.description,
+                    harmonizedCode=None,
+                    skuCode=None,
+                )
+                for package in packages
+            ],
+        ),
+        reference1=payload.reference,
+        reference2=None,
+        reference3=None,
+        transactionId=None,
+        signatureRequired=options.eshipper_signature_required.state,
+        insuranceType=None,
+        dangerousGoodsType=None,
+        pickup=None,
+        customsInformation=None,
+        customsInBondFreight=None,
+        cod=None,
+        isSaturdayService=options.eshipper_is_saturday_service.state,
+        holdForPickupRequired=options.eshipper_hold_for_pickup_required.state,
+        specialEquipment=options.eshipper_special_equipment.state,
+        insideDelivery=options.eshipper_inside_delivery.state,
+        deliveryAppointment=options.eshipper_delivery_appointment.state,
+        insidePickup=options.eshipper_inside_pickup.state,
+        saturdayPickupRequired=options.eshipper_saturday_pickup_required.state,
+        stackable=options.eshipper_stackable.state,
+        serviceId=service_id,
+        thirdPartyBilling=None,
+        commodityType=None,
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: lib.to_dict(lib.to_json(_).replace("raterequestfrom", "from")),
+    )

karrio/providers/eshipper/shipment/__init__.py

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

karrio/providers/eshipper/shipment/cancel.py

@@ -0,0 +1,45 @@
+import karrio.schemas.eshipper.cancel_request as eshipper
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.eshipper.error as error
+import karrio.providers.eshipper.utils as provider_utils
+import karrio.providers.eshipper.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 = not any(messages)
+
+    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:
+
+    request = eshipper.CancelRequestType(
+        order=eshipper.OrderType(
+            trackingId=None,
+            orderId=payload.options.get("orderId"),
+            message=None,
+        )
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/eshipper/shipment/create.py

@@ -0,0 +1,295 @@
+import karrio.schemas.eshipper.shipping_request as eshipper
+import karrio.schemas.eshipper.shipping_response as shipping
+import typing
+import datetime
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.eshipper.error as error
+import karrio.providers.eshipper.utils as provider_utils
+import karrio.providers.eshipper.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    shipment = _extract_details(response, settings) if "order" in response else None
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    shipment = lib.to_object(shipping.ShippingResponseType, data)
+    label_type = next((_.type for _ in shipment.labelData.label), "PDF").upper()
+    label = lib.bundle_base64([_.data for _ in shipment.labelData.label], label_type)
+    invoice = lib.failsafe(lambda: shipment.customsInvoice.data)
+    trackingNumbers = [_.trackingNumber for _ in shipment.packages]
+    service = provider_units.ShippingService.find(
+        shipment.carrier.serviceName,
+        test_mode=settings.test_mode,
+    )
+    rate_provider = provider_units.RateProvider.find(
+        shipment.carrier.carrierName,
+        test_mode=settings.test_mode,
+    )
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=shipment.trackingNumber,
+        shipment_identifier=shipment.order.id,
+        label_type=label_type,
+        docs=models.Documents(label=label, invoice=invoice),
+        meta=lib.to_dict(
+            dict(
+                service_name=service.name_or_key,
+                rate_provider=rate_provider.name_or_key,
+                carrier_tracking_link=shipment.trackingUrl,
+                tracking_numbers=trackingNumbers,
+                orderId=shipment.order.id,
+                transactionId=shipment.transactionId,
+                billingReference=shipment.billingReference,
+                eshipper_carrier_name=shipment.carrier.carrierName,
+            )
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    is_intl = shipper.country_code != recipient.country_code
+
+    payment = payload.payment or models.Payment()
+    payor = lib.to_address(
+        {
+            "sender": payload.shipper,
+            "recipient": payload.recipient,
+            "thid_party": payload.billing_address,
+        }.get(payment.paid_by)
+    )
+    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,
+    )
+    service = provider_units.ShippingService.map(payload.service)
+    service_id = lib.identity(
+        options.eshipper_service_id.state
+        or provider_units.ShippingService.service_id(
+            service.name_or_key,
+            test_mode=settings.test_mode,
+        )
+    )
+    carrier_id = lib.identity(
+        options.eshipper_carrier_id.state
+        or provider_units.ShippingService.carrier_id(
+            service.name_or_key,
+            service_id=service_id,
+            test_mode=settings.test_mode,
+            service_search=service.name_or_key,
+        )
+    )
+
+    customs = lib.to_customs_info(
+        payload.customs,
+        shipper=payload.shipper,
+        recipient=payload.recipient,
+        weight_unit=packages.weight_unit,
+        default_to=lib.identity(
+            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
+        ),
+    )
+
+    request = eshipper.ShippingRequestType(
+        scheduledShipDate=lib.fdatetime(
+            lib.to_next_business_datetime(
+                options.shipping_date.state or datetime.datetime.now(),
+                current_format="%Y-%m-%dT%H:%M",
+            ),
+            output_format="%Y-%m-%d %H:%M",
+        ),
+        shippingrequestfrom=eshipper.FromType(
+            attention=shipper.contact,
+            company=shipper.company_name,
+            address1=shipper.address_line1,
+            address2=shipper.address_line2,
+            city=shipper.city,
+            province=shipper.state_code,
+            country=shipper.country_code,
+            zip=shipper.postal_code,
+            email=shipper.email_address,
+            phone=shipper.phone_number,
+            instructions=None,
+            residential=shipper.is_residential,
+            tailgateRequired=None,
+            confirmDelivery=None,
+            notifyRecipient=None,
+        ),
+        to=eshipper.FromType(
+            attention=recipient.contact,
+            company=recipient.company_name,
+            address1=recipient.address_line1,
+            address2=recipient.address_line2,
+            city=recipient.city,
+            province=recipient.state_code,
+            country=recipient.country_code,
+            zip=recipient.postal_code,
+            email=recipient.email_address,
+            phone=recipient.phone_number,
+            instructions=None,
+            residential=recipient.is_residential,
+            tailgateRequired=None,
+            confirmDelivery=None,
+            notifyRecipient=None,
+        ),
+        packagingUnit="Metric" if packages.weight_unit.lower() == "kg" else "Imperial",
+        packages=eshipper.PackagesType(
+            type="Package",
+            packages=[
+                eshipper.PackageType(
+                    height=lib.to_int(package.height.value),
+                    length=lib.to_int(package.length.value),
+                    width=lib.to_int(package.width.value),
+                    weight=lib.to_int(package.weight.value),
+                    dimensionUnit=package.dimension_unit.value,
+                    weightUnit=package.weight_unit.value,
+                    type=provider_units.PackagingType.map(package.packaging_type).value,
+                    freightClass=package.parcel.freight_class,
+                    nmfcCode=None,
+                    insuranceAmount=package.options.insurance.state,
+                    codAmount=None,
+                    description=package.description,
+                    harmonizedCode=None,
+                    skuCode=None,
+                )
+                for package in packages
+            ],
+        ),
+        reference1=payload.reference,
+        reference2=None,
+        reference3=None,
+        transactionId=None,
+        signatureRequired=options.eshipper_signature_required.state,
+        insuranceType=None,
+        dangerousGoodsType=None,
+        pickup=None,
+        customsInformation=lib.identity(
+            eshipper.CustomsInformationType(
+                contact=eshipper.ContactType(
+                    contactCompany=shipper.company_name,
+                    contactName=shipper.contact,
+                    brokerName=None,
+                    brokerTaxId=None,
+                    recipientTaxId=None,
+                ),
+                items=eshipper.ItemsType(
+                    currency=(customs.duty.currency or options.currency.state),
+                    items=[
+                        eshipper.ItemType(
+                            hsnCode=item.hs_code,
+                            description=item.title or item.description,
+                            originCountry=item.origin_country,
+                            quantity=item.quantity,
+                            unitPrice=lib.to_money(item.value_amount),
+                            skuCode=item.sku,
+                        )
+                        for item in customs.commodities
+                    ],
+                ),
+                dutiesTaxes=eshipper.DutiesTaxesType(
+                    dutiable=not packages.is_document,
+                    billTo=customs.duty_billing_address.contact,
+                    accountNumber=customs.duty.account_number,
+                    sedNumber=customs.options.sed_number.state,
+                ),
+                billingAddress=eshipper.BillingAddressType(
+                    company=customs.duty_billing_address.company_name,
+                    attention=customs.duty_billing_address.contact,
+                    address1=customs.duty_billing_address.address_line1,
+                    address2=customs.duty_billing_address.address_line2,
+                    city=customs.duty_billing_address.city,
+                    province=customs.duty_billing_address.state_code,
+                    country=customs.duty_billing_address.country_code,
+                    zip=customs.duty_billing_address.postal_code,
+                    email=customs.duty_billing_address.email_address,
+                    phone=customs.duty_billing_address.phone_number,
+                ),
+                remarks=None,
+            )
+            if payload.customs
+            else None
+        ),
+        cod=lib.identity(
+            eshipper.CodType(
+                codAddress=eshipper.CodAddressType(
+                    company=recipient.company_name,
+                    name=recipient.contact,
+                    city=recipient.city,
+                    province=recipient.state_code,
+                    country=recipient.country_code,
+                    zip=recipient.postal_code,
+                ),
+                paymentType="Cash",
+            )
+            if options.cash_on_delivery.state
+            else None
+        ),
+        isSaturdayService=options.eshipper_is_saturday_service.state,
+        holdForPickupRequired=options.eshipper_hold_for_pickup_required.state,
+        specialEquipment=options.eshipper_special_equipment.state,
+        insideDelivery=options.eshipper_inside_delivery.state,
+        deliveryAppointment=options.eshipper_delivery_appointment.state,
+        insidePickup=options.eshipper_inside_pickup.state,
+        saturdayPickupRequired=options.eshipper_saturday_pickup_required.state,
+        stackable=options.eshipper_stackable.state,
+        serviceId=service_id,
+        thirdPartyBilling=lib.identity(
+            eshipper.ThirdPartyBillingType(
+                carrier=carrier_id,
+                country=payor.country_code,
+                billToAccountNumber=payment.account_number,
+                billToPostalCode=payor.postal_code,
+            )
+            if payment.paid_by == "third_party"
+            else None
+        ),
+        commodityType=customs.content_type,
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: lib.to_dict(lib.to_json(_).replace("shippingrequestfrom", "from")),
+    )

karrio/providers/eshipper/tracking.py

@@ -0,0 +1,72 @@
+import karrio.schemas.eshipper.tracking_request as eshipper
+import karrio.schemas.eshipper.tracking_response as tracking
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.eshipper.error as error
+import karrio.providers.eshipper.utils as provider_utils
+import karrio.providers.eshipper.units as provider_units
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[typing.Union[dict, typing.List[dict]]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    responses = response if isinstance(response, list) else [response]
+
+    messages: typing.List[models.Message] = sum(
+        [
+            error.parse_error_response(
+                _, settings, tracking_number=_.get("trackingNumber")
+            )
+            for _ in responses
+        ],
+        start=[],
+    )
+    tracking_details = [
+        _extract_details(_, settings)
+        for _ in responses
+        if _.get("trackingNumber") is not None
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    details = lib.to_object(tracking.TrackingResponseElementType, data)
+
+    return models.TrackingDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=details.trackingNumber,
+        events=[
+            models.TrackingEvent(
+                code=event.originalEvent.name,
+                location=event.location,
+                description=event.description,
+                date=lib.fdate(event.originalEvent.eventDate, "%Y-%m-%d %H:%M:%S"),
+                time=lib.flocaltime(event.originalEvent.eventDate, "%Y-%m-%d %H:%M:%S"),
+            )
+            for event in details.event
+        ],
+        estimated_delivery=lib.fdate(details.expectedDeliveryDate, "%Y-%m-%d %H:%M:%S"),
+        delivered=details.shipmentStatus.delivered,
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = eshipper.TrackingRequestType(
+        trackingNumbers=payload.tracking_numbers,
+        includePublished=True,
+        pageable=lib.to_json({"page": 0, "size": 25, "sort": []}),
+    )
+
+    return lib.Serializable(request, lib.to_dict)