karrio-dicom 2025.5rc1__py3-none-any.whl

karrio/providers/dicom/shipment/create.py

@@ -0,0 +1,192 @@
+from typing import Tuple, List
+from karrio.schemas.dicom.shipments import (
+    ShipmentRequest as DicomShipmentRequest,
+    Address as DicomAddress,
+    Parcel,
+    Surcharge,
+    Contact,
+    InternationalDetails,
+    Product,
+    Broker,
+    ShipmentResponse,
+)
+import karrio.lib as lib
+from karrio.core.units import Packages
+from karrio.core.utils import Serializable, DP
+from karrio.core.models import (
+    Documents,
+    ShipmentRequest,
+    ShipmentDetails,
+    Message,
+    Address,
+    Payment,
+)
+
+from karrio.providers.dicom.units import (
+    UnitOfMeasurement,
+    ParcelType,
+    Service,
+    ShippingOption,
+    PaymentType,
+    Purpose,
+)
+from karrio.providers.dicom.error import parse_error_response
+from karrio.providers.dicom.utils import Settings
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[dict],
+    settings: Settings,
+) -> Tuple[ShipmentDetails, List[Message]]:
+    response = _response.deserialize()
+    errors = parse_error_response(response, settings)
+    details = (
+        _extract_details(response, settings)
+        if all(key in response for key in ["label", "shipment"])
+        else None
+    )
+
+    return details, errors
+
+
+def _extract_details(response: dict, settings: Settings) -> ShipmentDetails:
+    label: str = response["label"]
+    shipment = DP.to_object(ShipmentResponse, response["shipment"])
+
+    return ShipmentDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=shipment.trackingNumber,
+        shipment_identifier=shipment.ID,
+        docs=Documents(label=label),
+    )
+
+
+def shipment_request(payload: ShipmentRequest, settings: Settings) -> Serializable:
+    packages = Packages(payload.parcels)
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    is_international = shipper.country_code != recipient.country_code
+    broker_info = payload.options.get("dicom_broker_info", {})
+    importer_info = (
+        Address(**payload.options.get("importer_info"))
+        if "importer_info" in payload.options
+        else None
+    )
+    payment = payload.payment or Payment("prepaid")
+    delivery_type = Service[payload.service].value
+    options = {
+        key: (value if ShippingOption[key].value in ["DCV", "COD"] else None)
+        for key, value in payload.options
+        if key in ShippingOption.__members__
+    }
+
+    request = DicomShipmentRequest(
+        paymentType=PaymentType[payment.paid_by or "prepaid"].value,
+        billingAccount=settings.billing_account,
+        sender=DicomAddress(
+            city=shipper.city,
+            provinceCode=shipper.state_code,
+            postalCode=shipper.postal_code,
+            countryCode=shipper.country_code,
+            customerName=shipper.company_name,
+            addressLine1=shipper.street,
+            addressLine2=shipper.address_line2,
+            contact=Contact(
+                fullName=shipper.person_name,
+                email=shipper.email,
+                telephone=shipper.phone_number,
+            ),
+        ),
+        consignee=DicomAddress(
+            city=recipient.city,
+            provinceCode=recipient.state_code,
+            postalCode=recipient.postal_code,
+            countryCode=recipient.country_code,
+            customerName=recipient.company_name,
+            addressLine1=recipient.street,
+            addressLine2=recipient.address_line2,
+            contact=Contact(
+                fullName=recipient.person_name,
+                email=recipient.email,
+                telephone=recipient.phone_number,
+            ),
+        ),
+        parcels=[
+            Parcel(
+                quantity=1,
+                parcelType=ParcelType[package.packaging_type or "dicom_box"].value,
+                weight=package.weight.KG,
+                length=package.height.CM,
+                depth=package.length.CM,
+                width=package.width.CM,
+                note=None,
+                status=None,
+                FCAClass=None,
+                hazmat=None,
+                requestReturnLabel=None,
+                returnWaybill=None,
+            )
+            for package in packages
+        ],
+        note=None,
+        category="Parcel",
+        pickupDate=None,
+        deliveryType=delivery_type,
+        trackingNumber=None,
+        unitOfMeasurement=UnitOfMeasurement.KC.value,
+        surcharges=[Surcharge(type=key, value=value) for key, value in options.items()],
+        promoCodes=None,
+        references=None,
+        returnAddress=None,
+        appointment=None,
+        internationalDetails=(
+            InternationalDetails(
+                isDicomBroker=(broker_info is not None),
+                descriptionOfGoods=payload.customs.content_description,
+                dutyBilling=payload.customs.duty.paid_by,
+                importerOfRecord=(
+                    DicomAddress(
+                        city=importer_info.city,
+                        provinceCode=importer_info.state_code,
+                        postalCode=importer_info.postal_code,
+                        countryCode=importer_info.country_code,
+                        customerName=importer_info.company_name,
+                        addressLine1=lib.text(
+                            importer_info.street_number, importer_info.address_line1
+                        ),
+                        addressLine2=importer_info.address_line2,
+                        contact=Contact(
+                            fullName=importer_info.person_name,
+                            email=importer_info.email,
+                            telephone=importer_info.phone_number,
+                        ),
+                    )
+                    if importer_info is not None
+                    else None
+                ),
+                broker=(
+                    Broker(
+                        id=broker_info.get("id"),
+                        CSA_BusinessNumber=broker_info.get("CSA_BusinessNumber"),
+                        otherBroker=broker_info.get("otherBroker"),
+                    )
+                    if broker_info is not None
+                    else None
+                ),
+                purpose=(
+                    Purpose[payload.customs.content_type].value
+                    if payload.customs.content_type is not None
+                    else None
+                ),
+                products=[
+                    Product(id=index, Quantity=product.quantity)
+                    for index, product in enumerate(payload.customs.commodities, 1)
+                ],
+            )
+            if is_international and payload.customs is not None
+            else None
+        ),
+    )
+
+    return Serializable(request)

karrio/providers/dicom/tracking.py

@@ -0,0 +1,47 @@
+from typing import Tuple, List
+from karrio.schemas.dicom.tracking import Tracking
+from karrio.core.utils import Serializable, DF, DP
+from karrio.core.models import TrackingRequest, TrackingDetails, TrackingEvent, Message
+
+from karrio.providers.dicom.error import parse_error_response
+from karrio.providers.dicom.utils import Settings
+import karrio.lib as lib
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[dict],
+    settings: Settings,
+) -> Tuple[List[TrackingDetails], List[Message]]:
+    response = _response.deserialize()
+    errors = [e for e in response if "activities" not in e]
+    details = [
+        _extract_detail(DP.to_object(Tracking, d), settings)
+        for d in response
+        if "activities" in d
+    ]
+
+    return details, parse_error_response(errors, settings)
+
+
+def _extract_detail(detail: Tracking, settings: Settings) -> TrackingDetails:
+    return TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.trackingNumber,
+        events=[
+            TrackingEvent(
+                date=DF.fdate(event.activityDate, "%Y-%m-%dT%H:%M:%SZ"),
+                description=event.statusDetail,
+                location=event.terminal,
+                code=event.status,
+                time=DF.ftime(event.activityDate, "%Y-%m-%dT%H:%M:%SZ"),
+            )
+            for event in detail.activities
+        ],
+    )
+
+
+def tracking_request(payload: TrackingRequest, _) -> Serializable:
+    request = payload.tracking_numbers
+
+    return Serializable(request)

karrio/providers/dicom/units.py

@@ -0,0 +1,167 @@
+import karrio.lib as lib
+import karrio.core.units as units
+
+
+class UnitOfMeasurement(lib.StrEnum):
+    K = "K"
+    L = "L"
+    KC = "KC"
+    KM = "KM"
+    LI = "LI"
+    LF = "LF"
+
+
+class Category(lib.StrEnum):
+    parcel = "Parcel"
+    freight = "Freight"
+    distribution = "Distribution"
+    logistics = "Logistics"
+
+
+class Purpose(lib.StrEnum):
+    com = "COM"
+    per = "PER"
+    doc = "DOC"
+    ret = "RET"
+
+    """ Unified Customs Content Type mapping """
+
+    documents = doc
+    gift = per
+    sample = per
+    merchandise = com
+    return_merchandise = ret
+    other = per
+
+
+class PaymentType(lib.StrEnum):
+    prepaid = "Prepaid"
+    third_party = "ThirdParty"
+    collect = "Collect"
+
+    """ Unified Payment Type mapping """
+
+    sender = prepaid
+    recipient = collect
+
+
+class ParcelType(lib.StrEnum):
+    dicom_barrel = "Barrel"
+    dicom_bundle = "Bundle"
+    dicom_box = "Box"
+    dicom_crate = "Crate"
+    dicom_full_load = "FullLoad"
+    dicom_mixed = "Mixed"
+    dicom_other = "Other"
+    dicom_piece = "Piece"
+    dicom_skid = "Skid"
+    dicom_tube = "Tube"
+    dicom_envelope = "Envelope"
+    dicom_maxpak = "Maxpak"
+    dicom_pallet = "Pallet"
+
+    """ Unified Packaging type mapping """
+
+    envelope = dicom_envelope
+    pak = dicom_maxpak
+    tube = dicom_tube
+    pallet = dicom_pallet
+    small_box = dicom_box
+    medium_box = dicom_box
+    your_packaging = dicom_other
+
+
+class Service(lib.StrEnum):  # DeliveryType
+    dicom_air_delivery = "AIR"
+    dicom_ground_delivery = "GRD"
+
+
+class ShippingOption(lib.Enum):
+    dicom_common_declared_value = lib.OptionEnum("DCV")
+    dicom_common_dangerous_goods = lib.OptionEnum("DGG")
+    dicom_common_residential_delivery = lib.OptionEnum("PHD")
+    dicom_common_tradeshow_delivery = lib.OptionEnum("TRD")
+    dicom_common_signature_not_required = lib.OptionEnum("SNR")
+    dicom_parcel_ca_hold_for_pickup = lib.OptionEnum("HFP")
+    dicom_parcel_ca_non_conveyable = lib.OptionEnum("NCV")
+    dicom_parcel_ca_residential_delivery_signature = lib.OptionEnum("PHDS")
+    dicom_parcel_ca_weekend_delivery = lib.OptionEnum("WKD")
+    dicom_freight_construction_site_delivery = lib.OptionEnum("CNSTD")
+    dicom_freight_collect_on_delivery = lib.OptionEnum("COD")
+    dicom_freight_heating = lib.OptionEnum("HEAT")
+    dicom_freight_inside_delivery = lib.OptionEnum("IDEL")
+    dicom_freight_residential_delivery_signature = lib.OptionEnum("PHDS")
+    dicom_freight_residential_pickup = lib.OptionEnum("PHPU")
+    dicom_freight_tailgate_delivery = lib.OptionEnum("TGT")
+    dicom_freight_tailgate_pickup = lib.OptionEnum("TGTPU")
+    dicom_parcel_us_adult_signature = lib.OptionEnum("ADLSIG")
+    dicom_parcel_us_direct_signature = lib.OptionEnum("DIRSIG")
+    dicom_parcel_us_saturday_delivery = lib.OptionEnum("SAT")
+    dicom_parcel_us_sunday_delivery = lib.OptionEnum("SUN")
+    dicom_parcel_us_residential_delivery_signature = lib.OptionEnum("PHDS")
+    dicom_parcel_us_earliest_possible = lib.OptionEnum("EP")
+    dicom_parcel_us_priority_service = lib.OptionEnum("PR")
+    dicom_parcel_us_pouch_service = lib.OptionEnum("PO")
+    dicom_parcel_us_pallet_service_pa = lib.OptionEnum("PA")
+    dicom_parcel_us_pallet_service_rap = lib.OptionEnum("RAP")
+    dicom_parcel_us_pallet_service_nd = lib.OptionEnum("ND")
+
+    """ Unified Option type mapping """
+    saturday_delivery = dicom_parcel_us_saturday_delivery
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: units.Options = None,
+) -> units.Options:
+    """
+    Apply default values to the given options.
+    """
+    _options = options.copy()
+
+    if package_options is not None:
+        _options.update(package_options.content)
+
+    return units.ShippingOptions(_options, ShippingOption)
+
+
+class Surcharge(lib.StrEnum):
+    dicom_common_base = "BAS"
+    dicom_common_declared_value = "DCV"
+    dicom_common_dangerous_goods = "DGG"
+    dicom_common_other_charge = "OTH"
+    dicom_common_residential_delivery = "PHD"
+    dicom_common_tradeshow_delivery = "TRD"
+    dicom_parcel_ca_collect_on_delivery = "COD"
+    dicom_parcel_ca_collect = "COL"
+    dicom_parcel_ca_chain_of_signature = "COS"
+    dicom_parcel_ca_dangerous_goods = "DGA"
+    dicom_parcel_ca_hold_for_pickup = "HFP"
+    dicom_parcel_ca_multi_pieces = "MPC"
+    dicom_parcel_ca_non_conveyable = "NCV"
+    dicom_parcel_ca_residential_delivery_signature = "PHS"
+    dicom_parcel_ca_over_36_inches = "O36"
+    dicom_parcel_ca_over_44_inches = "O44"
+    dicom_parcel_ca_over_96_inches = "O96"
+    dicom_parcel_ca_overweight = "OVW"
+    dicom_parcel_ca_signature_not_required = "SNR"
+    dicom_parcel_ca_trade_show = "TRD"
+    dicom_parcel_ca_weekend_delivery = "WKD"
+    dicom_parcel_ca_weekend_kilometers = "WKK"
+    dicom_parcel_ca_zone = "ZON"
+    dicom_parcel_ca_ontario_minimum_wage = "SMO"
+    dicom_parcel_ca_overweight_shipment = "OWS"
+    dicom_freight_construction_site_delivery = "CNSTD"
+    dicom_freight_collect_on_delivery = "COD"
+    dicom_freight_congestion_pickup = "CPU"
+    dicom_freight_heating = "HEAT"
+    dicom_freight_inside_delivery = "IDEL"
+    dicom_freight_pan_am_games_delivery = "PADL"
+    dicom_freight_pan_am_games_pickup = "PAPU"
+    dicom_freight_residential_delivery_signature = "PHDS"
+    dicom_freight_residential_pickup = "PHPU"
+    dicom_freight_promo_cash = "PRC"
+    dicom_freight_promo_pourcent = "PRP"
+    dicom_freight_single_pickup = "SPU"
+    dicom_freight_tailgate_delivery = "TGT"
+    dicom_freight_tailgate_pickup = "TGTPU"

karrio/providers/dicom/utils.py

@@ -0,0 +1,34 @@
+"""Karrio Dicom client settings."""
+
+from base64 import b64encode
+from karrio.core.settings import Settings as BaseSettings
+
+
+class Settings(BaseSettings):
+    """Dicom connection settings."""
+
+    # Carrier specific properties
+    username: str
+    password: str
+    billing_account: str = None
+
+    id: str = None
+    account_country_code: str = None
+    metadata: dict = {}
+
+    @property
+    def carrier_name(self):
+        return "dicom"
+
+    @property
+    def server_url(self):
+        return (
+            "https://sandbox-smart4i.dicom.com"
+            if self.test_mode
+            else "https://smart4i.dicom.com"
+        )
+
+    @property
+    def authorization(self):
+        pair = "%s:%s" % (self.username, self.password)
+        return b64encode(pair.encode("utf-8")).decode("ascii")

karrio/schemas/dicom/pickups.py

@@ -0,0 +1,83 @@
+import attr
+from jstruct import JStruct, JList, REQUIRED
+from typing import Optional, List
+
+
+@attr.s(auto_attribs=True)
+class Contact:
+    fullName: str
+    extension: Optional[int] = None
+    language: Optional[str] = None
+    email: Optional[str] = None
+    department: Optional[str] = None
+    telephone: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Shipment:
+    id: int
+    status: Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class Sender:
+    city: str
+    provinceCode: str
+    postalCode: str
+    countryCode: str
+    customerName: str
+
+    streetNumber: Optional[int] = None
+    suite: Optional[int] = None
+    addressLine1: Optional[str] = None
+    addressLine2: Optional[str] = None
+    streetType: Optional[str] = None
+    streetName: Optional[str] = None
+    streetDirection: Optional[str] = None
+    customerNickName: Optional[str] = None
+    contact: Optional[Contact] = JStruct[Contact]
+
+
+@attr.s(auto_attribs=True)
+class Shipment:
+    id: Optional[int] = None
+    status: Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class Pickup:
+    shipments: Optional[List[Shipment]] = JStruct[Shipment]
+    id: Optional[int] = None
+    officeClose: Optional[str] = None
+    date: Optional[str] = None
+    ready: Optional[str] = None
+    location: Optional[str] = None
+    otherLocation: Optional[str] = None
+    category: Optional[str] = None
+    sender: Optional[Sender] = JStruct[Sender]
+    contact: Optional[Contact] = JStruct[Contact]
+
+
+@attr.s(auto_attribs=True)
+class ShipmentPickupRequest:
+    date: str
+    ready: str
+    category: str
+    officeClose: str
+    contact: Contact = JStruct[Contact, REQUIRED]
+    shipments: List[Shipment] = JList[Shipment, REQUIRED]
+
+    location: Optional[str] = None
+    otherLocation: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupRequest:
+    date: str
+    ready: str
+    category: str
+    officeClose: str
+    sender: Sender = JStruct[Sender, REQUIRED]
+
+    location: Optional[str] = None
+    otherLocation: Optional[str] = None

karrio/schemas/dicom/rates.py

@@ -0,0 +1,126 @@
+import attr
+from jstruct import JStruct, JList, REQUIRED
+from typing import Optional, List
+
+
+@attr.s(auto_attribs=True)
+class Appointment:
+    type: str
+    date: Optional[str] = None
+    time: Optional[str] = None
+    phone: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Address:
+    postalCode: str
+    provinceCode: str
+    number: Optional[int] = None
+    countryCode: Optional[str] = None
+    name: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Hazmat:
+    number: int
+    phone: str
+
+
+@attr.s(auto_attribs=True)
+class Parcel:
+    quantity: int
+    parcelType: str
+
+    id: Optional[int] = None
+    weight: Optional[int] = None
+    length: Optional[int] = None
+    depth: Optional[int] = None
+    width: Optional[int] = None
+    note: Optional[str] = None
+    status: Optional[int] = None
+    FCA_Class: Optional[str] = None
+    hazmat: Optional[Hazmat] = JStruct[Hazmat]
+    requestReturnLabel: Optional[bool] = None
+    returnWaybill: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PromoCode:
+    code: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Surcharge:
+    type: str
+    id: Optional[int] = None
+    value: Optional[str] = None
+    name: Optional[str] = None
+    amount: Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class RateRequest:
+    category: str
+    paymentType: str
+    deliveryType: str
+    unitOfMeasurement: str
+    sender: Address = JStruct[Address, REQUIRED]
+    consignee: Address = JStruct[Address, REQUIRED]
+    parcels: List[Parcel] = JList[Parcel, REQUIRED]
+
+    billing: Optional[int] = None
+    promoCodes: Optional[List[PromoCode]] = JList[PromoCode]
+    surcharges: Optional[List[Surcharge]] = JList[Surcharge]
+    appointment: Optional[Appointment] = JStruct[Appointment]
+
+
+@attr.s(auto_attribs=True)
+class TaxesDetail:
+    type: Optional[str] = None
+    amount: Optional[str] = None
+    name: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Rate:
+    grossAmount: Optional[int] = None
+    discountAmount: Optional[int] = None
+    otherCharge: Optional[int] = None
+    fuelChargePercentage: Optional[int] = None
+    accountType: Optional[str] = None
+    rateType: Optional[str] = None
+    cubicWeight: Optional[float] = None
+    basicCharge: Optional[float] = None
+    weightCharge: Optional[float] = None
+    surcharges: List[Surcharge] = JList[Surcharge]
+    subTotal: Optional[float] = None
+    unitOfMeasurement: Optional[str] = None
+    taxesDetails: List[TaxesDetail] = JList[TaxesDetail]
+    taxes: Optional[float] = None
+    fuelCharge: Optional[float] = None
+    zoneCharge: Optional[float] = None
+    total: Optional[float] = None
+
+
+@attr.s(auto_attribs=True)
+class Reference:
+    code: Optional[int] = None
+    type: Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class RateResponse:
+    delay: Optional[int] = None
+    terminalLimit: Optional[int] = None
+    singleShipmentCost: Optional[int] = None
+    quantity: Optional[int] = None
+    rates: List[Rate] = JList[Rate]
+    references: List[Reference] = JList[Reference]
+    unitOfMeasurement: Optional[str] = None
+    parcelType: Optional[str] = None
+    weight: Optional[str] = None
+    postalCodeDelivery: Optional[str] = None
+    postalCodePickup: Optional[str] = None
+    creator: Optional[str] = None
+    date: Optional[str] = None
+    warning: Optional[str] = None