karrio-fedex 2025.5rc1__py3-none-any.whl

karrio/mappers/fedex/__init__.py

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

karrio/mappers/fedex/mapper.py

@@ -0,0 +1,89 @@
+"""Karrio FedEx client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.fedex as provider
+import karrio.mappers.fedex.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_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable:
+        return provider.shipment_cancel_request(payload, self.settings)
+
+    def create_document_upload_request(
+        self, payload: models.DocumentUploadRequest
+    ) -> lib.Serializable:
+        return provider.document_upload_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 parse_cancel_shipment_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+
+    def parse_rate_response(
+        self, response: lib.Deserializable
+    ) -> 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
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
+
+    def parse_tracking_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)
+
+    def parse_document_upload_response(
+        self,
+        response: lib.Deserializable,
+    ) -> typing.Tuple[models.DocumentUploadDetails, typing.List[models.Message]]:
+        return provider.parse_document_upload_response(response, self.settings)
+
+    def parse_cancel_pickup_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_cancel_response(response, self.settings)
+
+    def parse_pickup_response(
+        self, response: lib.Deserializable
+    ) -> 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
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_update_response(response, self.settings)

karrio/mappers/fedex/proxy.py

@@ -0,0 +1,144 @@
+import urllib.parse
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.providers.fedex.utils as provider_utils
+import karrio.mappers.fedex.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable:
+        response = lib.request(
+            url=f"{self.settings.server_url}/rate/v1/rates/quotes",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable:
+        response = lib.request(
+            url=f"{self.settings.server_url}/track/v1/trackingnumbers",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.track_access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        responses = lib.request(
+            url=f"{self.settings.server_url}/ship/v1/shipments",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(responses, lib.to_dict)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        response = lib.request(
+            url=f"{self.settings.server_url}/ship/v1/shipments/cancel",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def upload_document(self, requests: lib.Serializable) -> lib.Deserializable:
+        response = lib.run_asynchronously(
+            lambda _: lib.request(
+                url=(
+                    "https://documentapitest.prod.fedex.com/sandbox/documents/v1/etds/upload"
+                    if self.settings.test_mode
+                    else "https://documentapi.prod.fedex.com/documents/v1/etds/upload"
+                ),
+                data=urllib.parse.urlencode(_),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "content-Type": "multipart/form-data",
+                    "authorization": f"Bearer {self.settings.access_token}",
+                },
+            ),
+            requests.serialize(),
+        )
+
+        return lib.Deserializable(
+            response,
+            lambda __: [lib.to_dict(_) for _ in __],
+        )
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickup/v1/pickups",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def modify_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = self.cancel_pickup(lib.Serializable(request.ctx["cancel"]))
+        confirmation = response.deserialize().get("output") or {}
+
+        if confirmation.get("pickupConfirmationCode") is not None:
+            return self.schedule_pickup(request)
+
+        return response
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/pickup/v1/pickups/cancel",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="PUT",
+            headers={
+                "x-locale": "en_US",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.settings.access_token}",
+            },
+            decoder=provider_utils.parse_response,
+            on_error=lambda b: provider_utils.parse_response(b.read()),
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)

karrio/mappers/fedex/settings.py

@@ -0,0 +1,24 @@
+"""Karrio FedEx client settings."""
+
+import attr
+import jstruct
+import karrio.lib as lib
+import karrio.providers.fedex.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """FedEx connection settings."""
+
+    api_key: str = None
+    secret_key: str = None
+    account_number: str = None
+    track_api_key: str = None
+    track_secret_key: str = None
+
+    account_country_code: str = None
+    carrier_id: str = "fedex"
+    test_mode: bool = False
+    metadata: dict = {}
+    config: dict = {}
+    id: str = None

karrio/plugins/fedex/__init__.py

@@ -0,0 +1,23 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.fedex as mappers
+import karrio.providers.fedex.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="fedex",
+    label="FedEx",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    services=units.ShippingService,
+    options=units.ShippingOption,
+    connection_configs=units.ConnectionConfig,
+    has_intl_accounts=True,
+    # New fields
+    website="https://www.fedex.com",
+    description="FedEx Corporation is an American multinational conglomerate holding company which focuses on transportation, e-commerce and business services.",
+)

karrio/providers/fedex/__init__.py

@@ -0,0 +1,24 @@
+from karrio.providers.fedex.utils import Settings
+from karrio.providers.fedex.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.fedex.rate import rate_request, parse_rate_response
+from karrio.providers.fedex.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.fedex.document import (
+    parse_document_upload_response,
+    document_upload_request,
+)
+from karrio.providers.fedex.pickup import (
+    parse_pickup_cancel_response,
+    parse_pickup_update_response,
+    parse_pickup_response,
+    pickup_cancel_request,
+    pickup_update_request,
+    pickup_request,
+)

karrio/providers/fedex/document.py

@@ -0,0 +1,88 @@
+import karrio.schemas.fedex.paperless_request as fedex
+import time
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.fedex.error as provider_error
+import karrio.providers.fedex.units as provider_units
+import karrio.providers.fedex.utils as provider_utils
+
+
+def parse_document_upload_response(
+    _response: lib.Deserializable[typing.List[dict]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.DocumentUploadDetails, typing.List[models.Message]]:
+    responses = _response.deserialize()
+
+    metas = [_["output"]["meta"] for _ in responses if _.get("output", {}).get("meta")]
+    details = _extract_details(metas, settings) if len(metas) > 0 else None
+    errors = provider_error.parse_error_response([_ for _ in responses], settings)
+
+    return details, errors
+
+
+def _extract_details(
+    metas: typing.List[dict],
+    settings: provider_utils.Settings,
+) -> models.DocumentUploadDetails:
+    return models.DocumentUploadDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_id,
+        documents=[
+            models.DocumentDetails(
+                doc_id=meta["docId"],
+                file_name=meta["docId"],
+            )
+            for meta in metas
+        ],
+        meta=dict(),
+    )
+
+
+def document_upload_request(
+    payload: models.DocumentUploadRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    document_files = lib.to_document_files(payload.document_files)
+    options = lib.to_upload_options(
+        payload.options,
+        provider_units.DocumentUploadOption,
+    )
+    shipment_date = lib.fdatetime(
+        payload.shipment_date or time.strftime("%Y-%m-%d"),
+        current_format="%Y-%m-%d",
+        output_format="%Y%m%dT%H%M%S",
+    )
+
+    request = [
+        fedex.PaperlessRequestType(
+            document=fedex.DocumentType(
+                workflowName=(
+                    "ETDPreshipment"
+                    if options.pre_shipment.state
+                    else "ETDPostshipment"
+                ),
+                carrierCode=options.fedex_carrier_code.state,
+                name=document.doc_name,
+                contentType=document.doc_format,
+                meta=fedex.MetaType(
+                    shipDocumentType=(
+                        provider_units.UploadDocumentType.map(document.doc_type).value
+                        or provider_units.UploadDocumentType.other.value
+                    ),
+                    formCode=None,
+                    trackingNumber=payload.tracking_number,
+                    shipmentDate=shipment_date,
+                    originCountryCode=options.origin_country_code.state,
+                    destinationCountryCode=options.destination_country_code.state,
+                ),
+            ),
+            attachment=document.doc_file,
+        )
+        for document in document_files
+    ]
+
+    return lib.Serializable(
+        request,
+        lambda __: [lib.to_dict(_) for _ in __],
+    )

karrio/providers/fedex/error.py

@@ -0,0 +1,66 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+from karrio.providers.fedex.utils import Settings
+
+
+def parse_error_response(
+    response: typing.Union[typing.List[dict], dict],
+    settings: Settings,
+    **details,
+) -> typing.List[models.Message]:
+    responses = response if isinstance(response, list) else [response]
+    errors: typing.List[dict] = sum(
+        [
+            [
+                *(result["errors"] if "errors" in result else []),
+                *(
+                    result["output"]["alerts"]
+                    if "output" in result
+                    and not isinstance(result["output"], str)
+                    and "alerts" in result.get("output", {})
+                    and not isinstance(result["output"]["alerts"], str)
+                    else []
+                ),
+                *(
+                    [{"message": result["output"]["message"]}]
+                    if "output" in result
+                    and not isinstance(result["output"], str)
+                    and "message" in result.get("output", {})
+                    and isinstance(result["output"]["message"], str)
+                    and not result["output"].get("alertType") != "NOTE"
+                    else []
+                ),
+                *(
+                    [
+                        {
+                            **result["error"],
+                            "tracking_number": result.get("trackingNumberInfo", {}).get(
+                                "trackingNumber"
+                            ),
+                        }
+                    ]
+                    if "error" in result
+                    else []
+                ),
+            ]
+            for result in responses
+        ],
+        [],
+    )
+
+    return [
+        models.Message(
+            carrier_name=settings.carrier_name,
+            carrier_id=settings.carrier_id,
+            code=error.get("code"),
+            message=error.get("message"),
+            details=lib.to_dict(
+                {
+                    **details,
+                    "tracking_number": error.get("tracking_number"),
+                }
+            ),
+        )
+        for error in errors
+    ]

karrio/providers/fedex/pickup/__init__.py

@@ -0,0 +1,9 @@
+from karrio.providers.fedex.pickup.create import parse_pickup_response, pickup_request
+from karrio.providers.fedex.pickup.update import (
+    parse_pickup_update_response,
+    pickup_update_request,
+)
+from karrio.providers.fedex.pickup.cancel import (
+    parse_pickup_cancel_response,
+    pickup_cancel_request,
+)

karrio/providers/fedex/pickup/cancel.py

@@ -0,0 +1,79 @@
+import karrio.schemas.fedex.cancel_pickup_request as fedex
+import karrio.schemas.fedex.cancel_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.fedex.error as error
+import karrio.providers.fedex.utils as provider_utils
+import karrio.providers.fedex.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 = any(lib.failsafe(lambda: response["output"]["pickupConfirmationCode"]))
+
+    confirmation = lib.identity(
+        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:
+    address = lib.to_address(payload.address)
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "PickupOptions",
+            # fmt: off
+            {
+                "fedex_carrier_code": lib.OptionEnum("carrierCode"),
+                "fedex_pickup_location": lib.OptionEnum("location"),
+            },
+            # fmt: on
+        ),
+    )
+
+    # map data to convert karrio model to fedex specific type
+    request = fedex.CancelPickupRequestType(
+        associatedAccountNumber=fedex.AssociatedAccountNumberType(
+            value=settings.account_number,
+        ),
+        pickupConfirmationCode=payload.confirmation_number,
+        remarks=payload.reason,
+        carrierCode=options.fedex_carrier_code.state,
+        accountAddressOfRecord=lib.identity(
+            fedex.AccountAddressOfRecordType(
+                streetLines=address.address_lines,
+                urbanizationCode=None,
+                city=address.city,
+                stateOrProvinceCode=provider_utils.state_code(address),
+                postalCode=address.postal_code,
+                countryCode=address.country_code,
+                residential=address.residential,
+                addressClassification=None,
+            )
+            if payload.address
+            else None
+        ),
+        scheduledDate=lib.fdate(payload.pickup_date, "%Y-%m-%d"),
+        location=options.fedex_pickup_location.state,
+    )
+
+    return lib.Serializable(request, lib.to_dict)