karrio-usps 2025.5rc1__py3-none-any.whl

karrio/mappers/usps/__init__.py

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

karrio/mappers/usps/mapper.py

@@ -0,0 +1,94 @@
+"""Karrio USPS client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.usps as provider
+import karrio.mappers.usps.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(
+        self, payload: models.RateRequest
+    ) -> lib.Serializable:
+        return provider.rate_request(payload, self.settings)
+    
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+    
+    def create_shipment_request(
+        self, payload: models.ShipmentRequest
+    ) -> lib.Serializable:
+        return provider.shipment_request(payload, self.settings)
+    
+    def create_pickup_request(
+        self, payload: models.PickupRequest
+    ) -> lib.Serializable:
+        return provider.pickup_request(payload, self.settings)
+    
+    def create_pickup_update_request(
+        self, payload: models.PickupUpdateRequest
+    ) -> lib.Serializable:
+        return provider.pickup_update_request(payload, self.settings)
+    
+    def create_cancel_pickup_request(
+        self, payload: models.PickupCancelRequest
+    ) -> lib.Serializable:
+        return provider.pickup_cancel_request(payload, self.settings)
+    
+    def create_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable[str]:
+        return provider.shipment_cancel_request(payload, self.settings)
+    
+    def create_manifest_request(
+        self, payload: models.ManifestRequest
+    ) -> lib.Serializable:
+        return provider.manifest_request(payload, self.settings)
+    
+    
+    def parse_cancel_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_cancel_response(response, self.settings)
+    
+    def parse_cancel_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+    
+    def parse_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_response(response, self.settings)
+    
+    def parse_pickup_update_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_update_response(response, self.settings)
+    
+    def parse_rate_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return provider.parse_rate_response(response, self.settings)
+    
+    def parse_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
+    
+    def parse_tracking_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)
+    
+    def parse_manifest_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+        return provider.parse_manifest_response(response, self.settings)
+    

karrio/mappers/usps/proxy.py

@@ -0,0 +1,155 @@
+"""Karrio USPS client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.providers.usps.utils as provider_utils
+import karrio.mappers.usps.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.run_asynchronously(
+            lambda _: lib.request(
+                url=f"{self.settings.server_url}/shipments/v3/options/search",
+                data=lib.to_json(_),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.settings.access_token}",
+                },
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            response,
+            lambda _: [lib.to_dict(_) for _ in _],
+            request.ctx,
+        )
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.run_asynchronously(
+            lambda _: lib.request(
+                url=f"{self.settings.server_url}/labels/v3/label",
+                data=lib.to_json(_),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.settings.access_token}",
+                    "X-Payment-Authorization-Token": f"{self.settings.payment_token}",
+                },
+                on_error=provider_utils.parse_error_response,
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            response,
+            lambda _: [provider_utils.parse_response(_) for _ in _],
+            request.ctx,
+        )
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.run_asynchronously(
+            lambda _: (
+                _["trackingNumber"],
+                lib.request(
+                    url=f"{self.settings.server_url}/labels/v3/label/{_['trackingNumber']}",
+                    trace=self.trace_as("json"),
+                    method="DELETE",
+                    headers={
+                        "Content-Type": "application/json",
+                        "Authorization": f"Bearer {self.settings.access_token}",
+                        "X-Payment-Authorization-Token": f"{self.settings.payment_token}",
+                    },
+                ),
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            response,
+            lambda __: [(_[0], lib.to_dict(_[1])) for _ in __],
+        )
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.run_asynchronously(
+            lambda trackingNumber: (
+                trackingNumber,
+                lib.request(
+                    url=f"{self.settings.server_url}/tracking/v3/tracking/{trackingNumber}?expand=DETAIL",
+                    trace=self.trace_as("json"),
+                    method="GET",
+                    headers={
+                        "Content-Type": "application/json",
+                        "Authorization": f"Bearer {self.settings.access_token}",
+                    },
+                ),
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            response,
+            lambda __: [(_[0], lib.to_dict(_[1])) for _ in __],
+        )
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickup/v3/carrier-pickup",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickup/v3/carrier-pickup/{request.ctx['confirmationNumber']}",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickup/v3/carrier-pickup/{request.serialize()['confirmationNumber']}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+            on_ok=lambda _: '{"ok": true}',
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_manifest(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/scan-forms/v3/scan-form",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.settings.access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)

karrio/mappers/usps/settings.py

@@ -0,0 +1,26 @@
+"""Karrio USPS client settings."""
+
+import attr
+import karrio.providers.usps.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """USPS connection settings."""
+
+    # Add carrier specific API connection properties here
+    client_id: str
+    client_secret: str
+    account_number: str = None
+    account_type: provider_utils.AccountType = "EPS"  # type: ignore
+    manifest_MID: str = None
+    CRID: str = None
+    MID: str = None
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "usps"
+    account_country_code: str = "US"
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/usps/__init__.py

@@ -0,0 +1,24 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.usps as mappers
+import karrio.providers.usps.units as units
+import karrio.providers.usps.utils as utils
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="usps",
+    label="USPS",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=utils.ConnectionConfig,
+    # New fields
+    website="https://www.usps.com",
+    documentation="https://www.usps.com/business/web-tools-apis",
+    description="The United States Postal Service is an independent agency of the executive branch of the United States federal government responsible for providing postal service in the United States.",
+)

karrio/providers/usps/__init__.py

@@ -0,0 +1,26 @@
+"""Karrio USPS provider imports."""
+
+from karrio.providers.usps.utils import Settings
+from karrio.providers.usps.rate import parse_rate_response, rate_request
+from karrio.providers.usps.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.usps.pickup import (
+    parse_pickup_cancel_response,
+    parse_pickup_update_response,
+    parse_pickup_response,
+    pickup_update_request,
+    pickup_cancel_request,
+    pickup_request,
+)
+from karrio.providers.usps.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.usps.manifest import (
+    parse_manifest_response,
+    manifest_request,
+)

karrio/providers/usps/error.py

@@ -0,0 +1,56 @@
+"""Karrio USPS error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.usps.utils as provider_utils
+
+
+def parse_error_response(
+    response: typing.Union[dict, typing.List[dict]],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    responses = response if isinstance(response, list) else [response]
+    errors = [
+        *(
+            [response]
+            if isinstance(response, dict)
+            and isinstance(response.get("error"), dict)
+            and not any(response.get("error").get("errors") or [])
+            else []
+        ),
+        *(
+            [response]
+            if isinstance(response, dict) and isinstance(response.get("error"), str)
+            else []
+        ),
+        *(
+            response["error"]["errors"]
+            if isinstance(response, dict)
+            and isinstance(response.get("error"), dict)
+            and response.get("error").get("errors")
+            else []
+        ),
+    ]
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=lib.identity(error.get("code") or error.get("error")),
+            message=lib.identity(
+                error.get("message")
+                or error.get("detail")
+                or error.get("error_description", "")
+            ),
+            details=lib.to_dict(
+                {
+                    **kwargs,
+                    "source": error.get("source"),
+                    "error_uri": error.get("error_uri"),
+                }
+            ),
+        )
+        for error in errors
+    ]

karrio/providers/usps/manifest.py

@@ -0,0 +1,100 @@
+"""Karrio USPS manifest API implementation."""
+
+import karrio.schemas.usps.scan_form_request as usps
+import karrio.schemas.usps.scan_form_response as manifest
+
+import time
+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_manifest_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    details = lib.identity(
+        _extract_details(response, settings)
+        if response.get("SCANFormImage") is not None
+        else None
+    )
+
+    return details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.ManifestDetails:
+    details = lib.to_object(manifest.ScanFormResponseType, data)
+    image = data.get("SCANFormImage")
+
+    return models.ManifestDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_id,
+        doc=models.ManifestDocument(manifest=image),
+        meta=dict(
+            manifestNumber=details.SCANFormMetadata.manifestNumber,
+            trackingNumbers=details.SCANFormMetadata.trackingNumbers,
+        ),
+    )
+
+
+def manifest_request(
+    payload: models.ManifestRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "ManifestOptions",
+            # fmt: off
+            {
+                "shipment_date": lib.OptionEnum("shipment_date"),
+                "usps_ignore_bad_address": lib.OptionEnum("ignoreBadAddress", bool),
+                "usps_overwrite_mailing_date": lib.OptionEnum("overwriteMailingDate", bool),
+                "usps_destination_entry_facility_type": lib.OptionEnum("destinationEntryFacilityType", str),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to usps specific type
+    request = usps.ScanFormRequestType(
+        form="5630",
+        imageType="PDF",
+        labelType="8.5x11LABEL",
+        mailingDate=lib.fdate(options.shipment_date.state or time.strftime("%Y-%m-%d")),
+        overwriteMailingDate=options.usps_overwrite_mailing_date.state or False,
+        entryFacilityZIPCode=address.postal_code,
+        destinationEntryFacilityType=lib.identity(
+            options.usps_destination_entry_facility_type.state or "NONE"
+        ),
+        shipment=usps.ShipmentType(
+            trackingNumbers=payload.shipment_identifiers,
+        ),
+        fromAddress=usps.FromAddressType(
+            ignoreBadAddress=options.usps_ignore_bad_address.state or False,
+            streetAddress=address.address_line1,
+            secondaryAddress=address.address_line2,
+            city=address.city,
+            state=address.state,
+            ZIPCode=lib.to_zip5(address.postal_code) or "",
+            ZIPPlus4=lib.to_zip4(address.postal_code) or "",
+            urbanization=None,
+            firstName=lib.identity(
+                lib.failsafe(lambda: (address.person_name or "").split(" ")[0]) or ""
+            ),
+            lastName=lib.failsafe(lambda: (address.person_name or "").split(" ")[1]),
+            firm=address.company_name,
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/usps/pickup/__init__.py

@@ -0,0 +1,4 @@
+
+from karrio.providers.usps.pickup.create import parse_pickup_response, pickup_request
+from karrio.providers.usps.pickup.update import parse_pickup_update_response, pickup_update_request
+from karrio.providers.usps.pickup.cancel import parse_pickup_cancel_response, pickup_cancel_request

karrio/providers/usps/pickup/cancel.py

@@ -0,0 +1,40 @@
+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_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 = response.get("ok") == True
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Pickup",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def pickup_cancel_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+
+    # map data to convert karrio model to usps specific type
+    request = dict(confirmationNumber=payload.confirmation_number)
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/usps/pickup/create.py

@@ -0,0 +1,102 @@
+"""Karrio USPS schedule pickup implementation."""
+
+import karrio.schemas.usps.pickup_request as usps
+import karrio.schemas.usps.pickup_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_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.PickupResponseType, 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_request(
+    payload: models.PickupRequest,
+    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.PickupRequestType(
+        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)