karrio-usps 2025.5rc1__py3-none-any.whl

karrio/providers/usps/pickup/update.py

@@ -0,0 +1,109 @@
+"""Karrio USPS update pickup implementation."""
+
+import karrio.schemas.usps.pickup_update_request as usps
+import karrio.schemas.usps.pickup_update_response as pickup
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.usps.error as error
+import karrio.providers.usps.utils as provider_utils
+import karrio.providers.usps.units as provider_units
+
+
+def parse_pickup_update_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.PickupDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    pickup = (
+        _extract_details(response, settings)
+        if "confirmationNumber" in response
+        else None
+    )
+
+    return pickup, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.PickupDetails:
+    details = lib.to_object(pickup.PickupUpdateResponseType, data)
+
+    return models.PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=details.confirmationNumber,
+        pickup_date=lib.fdate(details.pickupDate),
+    )
+
+
+def pickup_update_request(
+    payload: models.PickupUpdateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+    packages = lib.to_packages(payload.parcels)
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "usps_package_type": lib.OptionEnum("usps_package_type"),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to usps specific type
+    request = usps.PickupUpdateRequestType(
+        pickupDate=lib.fdate(payload.pickup_date),
+        carrierPickupRequest=usps.CarrierPickupRequestType(
+            pickupDate=lib.fdate(payload.pickup_date),
+            pickupAddress=usps.PickupAddressType(
+                firstName=address.person_name,
+                lastName=None,
+                firm=address.company_name,
+                address=usps.AddressType(
+                    streetAddress=address.address_line1,
+                    secondaryAddress=address.address_line2,
+                    city=address.city,
+                    state=address.state,
+                    ZIPCode=lib.to_zip5(address.postal_code),
+                    ZIPPlus4=lib.to_zip4(address.postal_code) or "",
+                    urbanization=None,
+                ),
+                contact=[
+                    usps.ContactType(email=address.email)
+                    for _ in [address.email]
+                    if _ is not None
+                ],
+            ),
+            packages=[
+                usps.PackageType(
+                    packageType=options.usps_package_type.state or "OTHER",
+                    packageCount=len(packages),
+                )
+            ],
+            estimatedWeight=packages.weight.LB,
+            pickupLocation=lib.identity(
+                usps.PickupLocationType(
+                    packageLocation=payload.package_location,
+                    specialInstructions=payload.instruction,
+                )
+                if any([payload.package_location, payload.instruction])
+                else None
+            ),
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lib.to_dict,
+        dict(confirmationNumber=payload.confirmation_number),
+    )

karrio/providers/usps/rate.py

@@ -0,0 +1,204 @@
+"""Karrio USPS rating API implementation."""
+
+import karrio.schemas.usps.rate_request as usps
+import karrio.schemas.usps.rate_response as rating
+
+import time
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.core.errors as errors
+import karrio.providers.usps.error as error
+import karrio.providers.usps.utils as provider_utils
+import karrio.providers.usps.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]]:
+    responses = _response.deserialize()
+
+    messages = error.parse_error_response(responses, settings)
+    rates = lib.to_multi_piece_rates(
+        [
+            (
+                f"{_}",
+                [
+                    _ for _ in [
+                        _extract_details(dict(rate=rate, rateOption=rateOption), settings, _response.ctx)
+                        for pricingOption in response.get("pricingOptions", [])
+                        for shippingOption in pricingOption.get("shippingOptions", [])
+                        for rateOption in shippingOption.get("rateOptions", [])
+                        for rate in rateOption.get("rates", [])
+                    ]
+                    if _ is not None
+                ],
+            )
+            for _, response in enumerate(responses, start=1)
+        ]
+    )
+
+    return rates, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict = dict(),
+) -> typing.Optional[models.RateDetails]:
+    currency = "USD"
+    machinable_piece = data.get("machinable_piece")
+    rate = lib.to_object(rating.RateType, data['rate'])
+    rateOption = lib.to_object(rating.RateOptionType, data['rateOption'])
+    product_name = rate.productName or rate.description or rate.mailClass
+    service_code = provider_units.ShippingService.to_product_code(product_name)
+    service_name = provider_units.ShippingService.to_product_name(service_code)
+
+    if machinable_piece is True and "machinable" not in service_code:
+        return None
+    if machinable_piece is False and "machinable" in service_code:
+        return None
+
+    transit_days = lib.to_int(next(iter(rateOption.commitment.name.split(" "))))
+    estimated_delivery = rateOption.commitment.scheduleDeliveryDate
+    charges = [
+        ("Base Price", lib.to_money(rateOption.totalBasePrice)),
+        *[(extra.name, lib.to_money(extra.price)) for extra in rateOption.extraServices],
+    ]
+
+    return models.RateDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        service=service_code,
+        total_charge=lib.to_money(rateOption.totalPrice),
+        currency=currency,
+        extra_charges=[
+            models.ChargeDetails(
+                currency=currency,
+                amount=amount,
+                name=name,
+            )
+            for name, amount in charges
+        ],
+        estimated_delivery=estimated_delivery,
+        transit_days=transit_days,
+        meta=dict(
+            service_name=service_name,
+            usps_mail_class=rate.mailClass,
+            usps_guaranteed_delivery=lib.failsafe(lambda: rateOption.commitment.guaranteedDelivery),
+            usps_processing_category=lib.failsafe(lambda: rate.processingCategory),
+            usps_dimensional_weight=lib.failsafe(lambda: rate.dimensionalWeight),
+            usps_rate_indicator=lib.failsafe(lambda: rate.rateIndicator),
+            usps_price_type=lib.failsafe(lambda: rate.priceType),
+            usps_rate_sku=lib.failsafe(lambda: rate.SKU),
+            usps_zone=lib.failsafe(lambda: rate.zone),
+            rate_zone=lib.failsafe(lambda: rate.zone),
+            usps_extra_services=lib.failsafe(
+                lambda: [lib.to_int(_.extraService) for _ in rateOption.extraServices]
+            ),
+        ),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+
+    if (
+        shipper.country_code is not None
+        and shipper.country_code != units.Country.US.name
+    ):
+        raise errors.OriginNotServicedError(shipper.country_code)
+
+    if (
+        recipient.country_code is not None
+        and recipient.country_code != units.Country.US.name
+    ):
+        raise errors.DestinationNotServicedError(recipient.country_code)
+
+    services = lib.to_services(
+        [provider_units.ShippingService.to_mail_class(_).name_or_key for _ in payload.services],
+        provider_units.ShippingService
+    )
+    options = lib.to_shipping_options(
+        payload.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    packages = lib.to_packages(
+        payload.parcels,
+        options=options,
+        package_option_type=provider_units.ShippingOption,
+        shipping_options_initializer=provider_units.shipping_options_initializer,
+    )
+    price_type = lib.identity(
+        options.usps_price_type.state
+        or settings.connection_config.price_type.state
+        or "RETAIL"
+    )
+
+    package_mail_class = lambda package: lib.identity(
+        provider_units.ShippingService.to_mail_class(package.options.usps_mail_class.state).value
+        if package.options.usps_mail_class.state
+        else getattr(services.first, "value", "ALL")
+    )
+    package_options = lambda package: lib.identity(
+        package.options
+        if package_mail_class(package) not in provider_units.INCOMPATIBLE_SERVICES
+        else {}
+    )
+
+    # map data to convert karrio model to usps specific type
+    request = [
+        usps.RateRequestType(
+            pricingOptions=[
+                usps.PricingOptionType(
+                    priceType=price_type,
+                    paymentAccount=usps.PaymentAccountType(
+                        accountType=settings.account_type,
+                        accountNumber=settings.account_number,
+                    ),
+                )
+            ],
+            originZIPCode=shipper.postal_code,
+            destinationZIPCode=recipient.postal_code,
+            destinationEntryFacilityType=lib.identity(
+                options.usps_destination_entry_facility_type.state
+                or "NONE"
+            ),
+            packageDescription=usps.PackageDescriptionType(
+                weight=package.weight.LB,
+                length=package.length.IN,
+                height=package.height.IN,
+                width=package.width.IN,
+                girth=lib.identity(
+                    package.girth.value if package.packaging_type == "tube" else None
+                ),
+                mailClass=package_mail_class(package),
+                extraServices=[
+                    lib.to_int(_.code)
+                    for __, _ in package_options(package).items()
+                    if __ not in provider_units.CUSTOM_OPTIONS
+                ],
+                packageValue=package.options.package_value.state,
+                mailingDate=lib.fdate(
+                    package.options.shipment_date.state or time.strftime("%Y-%m-%d")
+                ),
+            ),
+            shippingFilter=package.options.usps_shipping_filter.state,
+        )
+        for package in packages
+    ]
+
+    return lib.Serializable(
+        request,
+        lib.to_dict,
+        dict(
+            price_type=price_type,
+            machinable_piece=options.usps_machinable_piece.state,
+        ),
+    )

karrio/providers/usps/shipment/__init__.py

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

karrio/providers/usps/shipment/cancel.py

@@ -0,0 +1,53 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.usps.error as error
+import karrio.providers.usps.utils as provider_utils
+import karrio.providers.usps.units as provider_units
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[typing.List[typing.Tuple[str, dict]]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    responses = _response.deserialize()
+    messages: typing.List[models.Message] = sum(
+        [
+            error.parse_error_response(response, settings, tracking_number=_)
+            for _, response in responses
+        ],
+        start=[],
+    )
+    success = all([_.get("status") == "CANCELED" for __, _ in responses])
+
+    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:
+
+    # map data to convert karrio model to usps specific type
+    request = [
+        dict(trackingNumber=_)
+        for _ in set(
+            [
+                payload.shipment_identifier,
+                *((payload.options or {}).get("shipment_identifiers") or []),
+            ]
+        )
+    ]
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/usps/shipment/create.py

@@ -0,0 +1,279 @@
+"""Karrio USPS create label implementation."""
+
+import karrio.schemas.usps.label_request as usps
+import karrio.schemas.usps.label_response as shipping
+
+import time
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.core.errors as errors
+import karrio.providers.usps.error as error
+import karrio.providers.usps.utils as provider_utils
+import karrio.providers.usps.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[typing.List[dict]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+    responses = _response.deserialize()
+    shipment = lib.to_multi_piece_shipment(
+        [
+            (
+                f"{_}",
+                _extract_details(response, settings, _response.ctx),
+            )
+            for _, response in enumerate(responses, start=1)
+            if response.get("error") is None
+            and response.get("labelMetadata") is not None
+        ]
+    )
+    messages: typing.List[models.Message] = sum(
+        [error.parse_error_response(response, settings) for response in responses],
+        start=[],
+    )
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict = None,
+) -> models.ShipmentDetails:
+    details = lib.to_object(shipping.LabelResponseType, data)
+    label = details.labelImage
+    invoice = details.receiptImage
+    label_type = ctx.get("label_type", "PDF")
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=details.labelMetadata.trackingNumber,
+        shipment_identifier=details.labelMetadata.trackingNumber,
+        label_type=label_type,
+        docs=models.Documents(label=label, invoice=invoice),
+        meta=dict(
+            SKU=details.labelMetadata.SKU,
+            postage=details.labelMetadata.postage,
+            routingInformation=details.labelMetadata.routingInformation,
+            labelBrokerID=details.labelMetadata.labelBrokerID,
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+
+    if (
+        shipper.country_code is not None
+        and shipper.country_code != units.Country.US.name
+    ):
+        raise errors.OriginNotServicedError(shipper.country_code)
+
+    if (
+        recipient.country_code is not None
+        and recipient.country_code != units.Country.US.name
+    ):
+        raise errors.DestinationNotServicedError(recipient.country_code)
+
+    return_address = lib.to_address(payload.return_address)
+    mail_class = lib.identity(
+        provider_units.ShippingService.to_mail_class(payload.service).value
+        or payload.service
+    )
+    options = lib.to_shipping_options(
+        payload.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    packages = lib.to_packages(
+        payload.parcels,
+        options=options,
+        package_option_type=provider_units.ShippingOption,
+        shipping_options_initializer=provider_units.shipping_options_initializer,
+    )
+    pickup_location = lib.to_address(options.hold_for_pickup_address.state)
+    label_type = provider_units.LabelType.map(payload.label_type).value or "PDF"
+
+    package_options = lambda package: lib.identity(
+        package.options
+        if mail_class not in provider_units.INCOMPATIBLE_SERVICES
+        else {}
+    )
+
+    # map data to convert karrio model to usps specific type
+    request = [
+        usps.LabelRequestType(
+            imageInfo=usps.ImageInfoType(
+                imageType=label_type,
+                labelType="4X6LABEL",
+                # shipInfo=None,
+                receiptOption="NONE",
+                suppressPostage=None,
+                suppressMailDate=None,
+                returnLabel=None,
+            ),
+            toAddress=usps.AddressType(
+                streetAddress=recipient.address_line1,
+                secondaryAddress=recipient.address_line2,
+                city=recipient.city,
+                state=recipient.state_code,
+                ZIPCode=lib.to_zip5(recipient.postal_code) or "",
+                ZIPPlus4=lib.to_zip4(recipient.postal_code) or "",
+                urbanization=None,
+                firstName=recipient.first_name,
+                lastName=recipient.last_name,
+                firm=recipient.company_name,
+                phone=provider_utils.parse_phone_number(recipient.phone_number),
+                email=recipient.email,
+                ignoreBadAddress=True,
+                platformUserId=None,
+                parcelLockerDelivery=None,
+                holdForPickup=package.options.usps_hold_for_pickup.state,
+                facilityId=package.options.usps_facility_id.state,
+            ),
+            fromAddress=usps.AddressType(
+                streetAddress=shipper.address_line1,
+                secondaryAddress=shipper.address_line2,
+                city=shipper.city,
+                state=shipper.state_code,
+                ZIPCode=lib.to_zip5(shipper.postal_code) or "",
+                ZIPPlus4=lib.to_zip4(shipper.postal_code) or "",
+                urbanization=None,
+                firstName=shipper.first_name,
+                lastName=shipper.last_name,
+                firm=shipper.company_name,
+                phone=provider_utils.parse_phone_number(shipper.phone_number),
+                email=shipper.email,
+                ignoreBadAddress=True,
+                platformUserId=None,
+                parcelLockerDelivery=None,
+                holdForPickup=None,
+                facilityId=None,
+            ),
+            senderAddress=usps.AddressType(
+                streetAddress=shipper.address_line1,
+                secondaryAddress=shipper.address_line2r,
+                city=shipper.city,
+                state=shipper.state_code,
+                ZIPCode=lib.to_zip5(shipper.postal_code) or "",
+                ZIPPlus4=lib.to_zip4(shipper.postal_code) or "",
+                urbanization=None,
+                firstName=shipper.first_name,
+                lastName=shipper.last_name,
+                firm=shipper.company_name,
+                phone=provider_utils.parse_phone_number(shipper.phone_number),
+                email=shipper.email,
+                ignoreBadAddress=True,
+                platformUserId=None,
+                parcelLockerDelivery=None,
+                holdForPickup=None,
+                facilityId=None,
+            ),
+            returnAddress=lib.identity(
+                usps.AddressType(
+                    streetAddress=return_address.address_line1,
+                    secondaryAddress=return_address.address_line2r,
+                    city=return_address.city,
+                    state=return_address.state_code,
+                    ZIPCode=lib.to_zip5(return_address.postal_code) or "",
+                    ZIPPlus4=lib.to_zip4(return_address.postal_code) or "",
+                    urbanization=None,
+                    firstName=return_address.first_name,
+                    lastName=return_address.last_name,
+                    firm=return_address.company_name,
+                    phone=provider_utils.parse_phone_number(return_address.phone_number),
+                    email=return_address.email,
+                    ignoreBadAddress=True,
+                    platformUserId=None,
+                    parcelLockerDelivery=None,
+                    holdForPickup=None,
+                    facilityId=None,
+                )
+                if payload.return_address is not None
+                else None
+            ),
+            packageDescription=usps.PackageDescriptionType(
+                weightUOM="lb",
+                weight=package.weight.LB,
+                dimensionsUOM="in",
+                length=package.length.IN,
+                height=package.height.IN,
+                width=package.width.IN,
+                girth=package.girth.value,
+                mailClass=mail_class,
+                rateIndicator=package.options.usps_rate_indicator.state or "DR",
+                processingCategory=lib.identity(
+                    package.options.usps_processing_category.state or "NON_MACHINABLE"
+                ),
+                destinationEntryFacilityType=lib.identity(
+                    package.options.usps_destination_facility_type.state or "NONE"
+                ),
+                destinationEntryFacilityAddress=lib.identity(
+                    usps.DestinationEntryFacilityAddressType(
+                        streetAddress=pickup_location.address_line1,
+                        secondaryAddress=pickup_location.address_line2r,
+                        city=pickup_location.city,
+                        state=pickup_location.state_code,
+                        ZIPCode=lib.to_zip5(pickup_location.postal_code) or "",
+                        ZIPPlus4=lib.to_zip4(pickup_location.postal_code) or "",
+                        urbanization=None,
+                    )
+                    if package.options.hold_for_pickup_address.state is not None
+                    else None
+                ),
+                packageOptions=lib.identity(
+                    usps.PackageOptionsType(
+                        packageValue=lib.identity(
+                            package.total_value
+                            or package.options.declared_value.state
+                            or 1.0
+                        ),
+                        nonDeliveryOption=None,
+                        redirectAddress=None,
+                        contentType=None,
+                        generateGXEvent=None,
+                        containers=[],
+                        ancillaryServiceEndorsements=None,
+                        originalPackage=None,
+                    )
+                    if (package.total_value or package.options.declared_value.state)
+                    else None
+                ),
+                customerReference=[
+                    usps.CustomerReferenceType(
+                        referenceNumber=reference,
+                        printReferenceNumber=True,
+                    )
+                    for reference in [payload.reference]
+                    if reference is not None
+                ],
+                extraServices=lib.identity(
+                    package.options.usps_extra_services.state
+                    or [
+                        lib.to_int(_.code)
+                        for __, _ in package_options(package).items()
+                        if _.name not in provider_units.CUSTOM_OPTIONS
+                    ]
+                ),
+                mailingDate=lib.fdate(
+                    package.options.shipment_date.state or time.strftime("%Y-%m-%d")
+                ),
+                carrierRelease=package.options.usps_carrier_release.state,
+                physicalSignatureRequired=package.options.usps_physical_signature_required.state,
+                inductionZIPCode=lib.identity(
+                    return_address.postal_code or shipper.postal_code
+                ),
+            ),
+            customsForm=None,
+        )
+        for package in packages
+    ]
+
+    return lib.Serializable(request, lib.to_dict, dict(label_type=label_type))