karrio-fedex 2025.5rc1__py3-none-any.whl

karrio/providers/fedex/utils.py

@@ -0,0 +1,199 @@
+import karrio.schemas.fedex.tracking_document_request as fedex
+import gzip
+import typing
+import datetime
+import urllib.parse
+import karrio.lib as lib
+import karrio.core as core
+import karrio.core.errors as errors
+
+
+class Settings(core.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
+    metadata: dict = {}
+    config: dict = {}
+    id: str = None
+
+    @property
+    def carrier_name(self):
+        return "fedex"
+
+    @property
+    def server_url(self):
+        return (
+            "https://apis-sandbox.fedex.com"
+            if self.test_mode
+            else "https://apis.fedex.com"
+        )
+
+    @property
+    def tracking_url(self):
+        return "https://www.fedex.com/fedextrack/?trknbr={}"
+
+    @property
+    def connection_config(self) -> lib.units.Options:
+        from karrio.providers.fedex.units import ConnectionConfig
+
+        return lib.to_connection_config(
+            self.config or {},
+            option_type=ConnectionConfig,
+        )
+
+    @property
+    def default_currency(self) -> typing.Optional[str]:
+        return lib.units.CountryCurrency.map(self.account_country_code).value
+
+    @property
+    def access_token(self):
+        """Retrieve the access_token using the api_key|secret_key pair
+        or collect it from the cache if an unexpired access_token exist.
+        """
+        if not all([self.api_key, self.secret_key, self.account_number]):
+            raise Exception(
+                "The api_key, secret_key and account_number are required for Rate, Ship and Other API requests."
+            )
+
+        cache_key = f"{self.carrier_name}|{self.api_key}|{self.secret_key}"
+        now = datetime.datetime.now() + datetime.timedelta(minutes=30)
+
+        auth = self.connection_cache.get(cache_key) or {}
+        token = auth.get("access_token")
+        expiry = lib.to_date(auth.get("expiry"), current_format="%Y-%m-%d %H:%M:%S")
+
+        if token is not None and expiry is not None and expiry > now:
+            return token
+
+        self.connection_cache.set(
+            cache_key,
+            lambda: login(
+                self,
+                client_id=self.api_key,
+                client_secret=self.secret_key,
+            ),
+        )
+        new_auth = self.connection_cache.get(cache_key)
+
+        return new_auth["access_token"]
+
+    @property
+    def track_access_token(self):
+        """Retrieve the access_token using the track_api_key|track_secret_key pair
+        or collect it from the cache if an unexpired access_token exist.
+        """
+        if not all([self.track_api_key, self.track_secret_key]):
+            raise Exception(
+                "The track_api_key and track_secret_key are required for Track API requests."
+            )
+
+        cache_key = f"{self.carrier_name}|{self.track_api_key}|{self.track_secret_key}"
+        now = datetime.datetime.now() + datetime.timedelta(minutes=30)
+
+        auth = self.connection_cache.get(cache_key) or {}
+        token = auth.get("access_token")
+        expiry = lib.to_date(auth.get("expiry"), current_format="%Y-%m-%d %H:%M:%S")
+
+        if token is not None and expiry is not None and expiry > now:
+            return token
+
+        self.connection_cache.set(
+            cache_key,
+            lambda: login(
+                self,
+                client_id=self.track_api_key,
+                client_secret=self.track_secret_key,
+            ),
+        )
+        new_auth = self.connection_cache.get(cache_key)
+
+        return new_auth["access_token"]
+
+
+def login(settings: Settings, client_id: str = None, client_secret: str = None):
+    import karrio.providers.fedex.error as error
+
+    result = lib.request(
+        url=f"{settings.server_url}/oauth/token",
+        method="POST",
+        headers={
+            "content-Type": "application/x-www-form-urlencoded",
+        },
+        data=urllib.parse.urlencode(
+            dict(
+                grant_type="client_credentials",
+                client_id=client_id,
+                client_secret=client_secret,
+            )
+        ),
+    )
+
+    response = lib.to_dict(result)
+    messages = error.parse_error_response(response, settings)
+
+    if any(messages):
+        raise errors.ParsedMessagesError(messages)
+
+    expiry = datetime.datetime.now() + datetime.timedelta(
+        seconds=float(response.get("expires_in", 0))
+    )
+
+    return {**response, "expiry": lib.fdatetime(expiry)}
+
+
+def get_proof_of_delivery(tracking_number: str, settings: Settings):
+    import karrio.providers.fedex.error as error
+
+    request = fedex.TrackingDocumentRequestType(
+        trackDocumentSpecification=[
+            fedex.TrackDocumentSpecificationType(
+                trackingNumberInfo=fedex.TrackingNumberInfoType(
+                    trackingNumber=tracking_number
+                )
+            )
+        ],
+        trackDocumentDetail=fedex.TrackDocumentDetailType(
+            documentType="SIGNATURE_PROOF_OF_DELIVERY",
+            documentFormat="PNG",
+        ),
+    )
+    response = lib.to_dict(
+        lib.request(
+            url=f"{settings.server_url}/track/v1/trackingdocuments",
+            data=lib.to_json(request),
+            method="POST",
+            decoder=parse_response,
+            on_error=lambda b: parse_response(b.read()),
+        )
+    )
+
+    messages = error.parse_error_response(response, settings)
+
+    if any(messages):
+        return None
+
+    return lib.failsafe(
+        lambda: lib.bundle_base64(response["output"]["documents"], format="PNG")
+    )
+
+
+def parse_response(binary_string):
+    content = lib.failsafe(lambda: gzip.decompress(binary_string)) or binary_string
+    return lib.decode(content)
+
+
+def state_code(address: lib.units.ComputedAddress) -> str:
+    if address.state_code is None:
+        return None
+
+    return (
+        "PQ"
+        if address.state_code.lower() == "qc" and address.country_code == "CA"
+        else address.state_code
+    )

karrio/schemas/fedex/cancel_pickup_request.py

@@ -0,0 +1,31 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AccountAddressOfRecordType:
+    streetLines: typing.Optional[typing.List[str]] = None
+    urbanizationCode: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    stateOrProvinceCode: typing.Optional[str] = None
+    postalCode: typing.Optional[int] = None
+    countryCode: typing.Optional[str] = None
+    residential: typing.Optional[bool] = None
+    addressClassification: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class AssociatedAccountNumberType:
+    value: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CancelPickupRequestType:
+    associatedAccountNumber: typing.Optional[AssociatedAccountNumberType] = jstruct.JStruct[AssociatedAccountNumberType]
+    pickupConfirmationCode: typing.Optional[int] = None
+    remarks: typing.Optional[str] = None
+    carrierCode: typing.Optional[str] = None
+    accountAddressOfRecord: typing.Optional[AccountAddressOfRecordType] = jstruct.JStruct[AccountAddressOfRecordType]
+    scheduledDate: typing.Optional[str] = None
+    location: typing.Optional[str] = None

karrio/schemas/fedex/cancel_pickup_response.py

@@ -0,0 +1,24 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AlertType:
+    code: typing.Optional[str] = None
+    alertType: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class OutputType:
+    pickupConfirmationCode: typing.Optional[str] = None
+    cancelConfirmationMessage: typing.Optional[str] = None
+    alerts: typing.Optional[typing.List[AlertType]] = jstruct.JList[AlertType]
+
+
+@attr.s(auto_attribs=True)
+class CancelPickupResponseType:
+    transactionId: typing.Optional[str] = None
+    customerTransactionId: typing.Optional[str] = None
+    output: typing.Optional[OutputType] = jstruct.JStruct[OutputType]

karrio/schemas/fedex/cancel_request.py

@@ -0,0 +1,17 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AccountNumberType:
+    value: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CancelRequestType:
+    accountNumber: typing.Optional[AccountNumberType] = jstruct.JStruct[AccountNumberType]
+    emailShipment: typing.Optional[bool] = None
+    senderCountryCode: typing.Optional[str] = None
+    deletionControl: typing.Optional[str] = None
+    trackingNumber: typing.Optional[str] = None

karrio/schemas/fedex/cancel_response.py

@@ -0,0 +1,25 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AlertType:
+    code: typing.Optional[str] = None
+    alertType: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class OutputType:
+    cancelledShipment: typing.Optional[bool] = None
+    cancelledHistory: typing.Optional[bool] = None
+    successMessage: typing.Optional[str] = None
+    alerts: typing.Optional[typing.List[AlertType]] = jstruct.JList[AlertType]
+
+
+@attr.s(auto_attribs=True)
+class CancelResponseType:
+    transactionId: typing.Optional[str] = None
+    customerTransactionId: typing.Optional[str] = None
+    output: typing.Optional[OutputType] = jstruct.JStruct[OutputType]

karrio/schemas/fedex/error_response.py

@@ -0,0 +1,16 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ErrorType:
+    code: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ErrorResponseType:
+    transactionId: typing.Optional[str] = None
+    customerTransactionId: typing.Optional[str] = None
+    errors: typing.Optional[typing.List[ErrorType]] = jstruct.JList[ErrorType]

karrio/schemas/fedex/paperless_request.py

@@ -0,0 +1,30 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class MetaType:
+    shipDocumentType: typing.Optional[str] = None
+    formCode: typing.Optional[str] = None
+    trackingNumber: typing.Optional[str] = None
+    shipmentDate: typing.Optional[str] = None
+    originLocationCode: typing.Optional[str] = None
+    originCountryCode: typing.Optional[str] = None
+    destinationLocationCode: typing.Optional[str] = None
+    destinationCountryCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class DocumentType:
+    workflowName: typing.Optional[str] = None
+    carrierCode: typing.Optional[str] = None
+    name: typing.Optional[str] = None
+    contentType: typing.Optional[str] = None
+    meta: typing.Optional[MetaType] = jstruct.JStruct[MetaType]
+
+
+@attr.s(auto_attribs=True)
+class PaperlessRequestType:
+    document: typing.Optional[DocumentType] = jstruct.JStruct[DocumentType]
+    attachment: typing.Optional[str] = None

karrio/schemas/fedex/paperless_response.py

@@ -0,0 +1,21 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class MetaType:
+    documentType: typing.Optional[str] = None
+    docId: typing.Optional[str] = None
+    folderId: typing.Optional[typing.List[str]] = None
+
+
+@attr.s(auto_attribs=True)
+class OutputType:
+    meta: typing.Optional[MetaType] = jstruct.JStruct[MetaType]
+
+
+@attr.s(auto_attribs=True)
+class PaperlessResponseType:
+    output: typing.Optional[OutputType] = jstruct.JStruct[OutputType]
+    customerTransactionId: typing.Optional[str] = None

karrio/schemas/fedex/pickup_request.py

@@ -0,0 +1,106 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AccountAddressOfRecordType:
+    streetLines: typing.Optional[typing.List[str]] = None
+    city: typing.Optional[str] = None
+    stateOrProvinceCode: typing.Optional[str] = None
+    postalCode: typing.Optional[int] = None
+    countryCode: typing.Optional[str] = None
+    residential: typing.Optional[bool] = None
+    addressClassification: typing.Optional[str] = None
+    urbanizationCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class AccountNumberType:
+    value: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class DimensionsType:
+    length: typing.Optional[int] = None
+    width: typing.Optional[int] = None
+    height: typing.Optional[int] = None
+    units: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ExpressFreightDetailType:
+    truckType: typing.Optional[str] = None
+    service: typing.Optional[str] = None
+    trailerLength: typing.Optional[str] = None
+    bookingNumber: typing.Optional[str] = None
+    dimensions: typing.Optional[DimensionsType] = jstruct.JStruct[DimensionsType]
+
+
+@attr.s(auto_attribs=True)
+class ContactType:
+    companyName: typing.Optional[str] = None
+    personName: typing.Optional[str] = None
+    phoneNumber: typing.Optional[str] = None
+    phoneExtension: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupLocationType:
+    contact: typing.Optional[ContactType] = jstruct.JStruct[ContactType]
+    address: typing.Optional[AccountAddressOfRecordType] = jstruct.JStruct[AccountAddressOfRecordType]
+    accountNumber: typing.Optional[AccountNumberType] = jstruct.JStruct[AccountNumberType]
+    deliveryInstructions: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class OriginDetailType:
+    pickupAddressType: typing.Optional[str] = None
+    pickupLocation: typing.Optional[PickupLocationType] = jstruct.JStruct[PickupLocationType]
+    readyDateTimestamp: typing.Optional[str] = None
+    customerCloseTime: typing.Optional[str] = None
+    pickupDateType: typing.Optional[str] = None
+    packageLocation: typing.Optional[str] = None
+    buildingPart: typing.Optional[str] = None
+    buildingPartDescription: typing.Optional[int] = None
+    earlyPickup: typing.Optional[bool] = None
+    suppliesRequested: typing.Optional[str] = None
+    geographicalPostalCode: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class EmailDetailType:
+    address: typing.Optional[str] = None
+    locale: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupNotificationDetailType:
+    emailDetails: typing.Optional[typing.List[EmailDetailType]] = jstruct.JList[EmailDetailType]
+    format: typing.Optional[str] = None
+    userMessage: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class TotalWeightType:
+    units: typing.Optional[str] = None
+    value: typing.Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupRequestType:
+    associatedAccountNumber: typing.Optional[AccountNumberType] = jstruct.JStruct[AccountNumberType]
+    originDetail: typing.Optional[OriginDetailType] = jstruct.JStruct[OriginDetailType]
+    associatedAccountNumberType: typing.Optional[str] = None
+    totalWeight: typing.Optional[TotalWeightType] = jstruct.JStruct[TotalWeightType]
+    packageCount: typing.Optional[int] = None
+    carrierCode: typing.Optional[str] = None
+    accountAddressOfRecord: typing.Optional[AccountAddressOfRecordType] = jstruct.JStruct[AccountAddressOfRecordType]
+    remarks: typing.Optional[str] = None
+    countryRelationships: typing.Optional[str] = None
+    pickupType: typing.Optional[str] = None
+    trackingNumber: typing.Optional[str] = None
+    commodityDescription: typing.Optional[str] = None
+    expressFreightDetail: typing.Optional[ExpressFreightDetailType] = jstruct.JStruct[ExpressFreightDetailType]
+    oversizePackageCount: typing.Optional[int] = None
+    pickupNotificationDetail: typing.Optional[PickupNotificationDetailType] = jstruct.JStruct[PickupNotificationDetailType]

karrio/schemas/fedex/pickup_response.py

@@ -0,0 +1,25 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AlertType:
+    code: typing.Optional[str] = None
+    alertType: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class OutputType:
+    pickupConfirmationCode: typing.Optional[int] = None
+    message: typing.Optional[str] = None
+    location: typing.Optional[str] = None
+    alerts: typing.Optional[typing.List[AlertType]] = jstruct.JList[AlertType]
+
+
+@attr.s(auto_attribs=True)
+class PickupResponseType:
+    transactionId: typing.Optional[str] = None
+    customerTransactionId: typing.Optional[str] = None
+    output: typing.Optional[OutputType] = jstruct.JStruct[OutputType]