karrio-aramex 2025.5rc34__py3-none-any.whl

karrio/mappers/aramex/__init__.py

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

karrio/mappers/aramex/mapper.py

@@ -0,0 +1,20 @@
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.aramex as provider
+import karrio.mappers.aramex.settings as settings
+
+
+class Mapper(mapper.Mapper):
+    settings: settings.Settings
+
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, 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)

karrio/mappers/aramex/proxy.py

@@ -0,0 +1,22 @@
+from karrio.core.utils import XP, request as http, Serializable, Deserializable
+from karrio.api.proxy import Proxy as BaseProxy
+from karrio.mappers.aramex.settings import Settings
+
+
+class Proxy(BaseProxy):
+    settings: Settings
+
+    """ Proxy Methods """
+
+    def get_tracking(self, request: Serializable) -> Deserializable:
+        response = http(
+            url=f"{self.settings.server_url}/ShippingAPI.V2/Tracking/Service_1_0.svc",
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "text/xml; charset=utf-8",
+                "soapAction": "http://ws.aramex.net/ShippingAPI/v1/Service_1_0/TrackShipments",
+            },
+        )
+        return Deserializable(response, XP.to_xml)

karrio/mappers/aramex/settings.py

@@ -0,0 +1,24 @@
+"""Karrio Aramex settings."""
+
+import attr
+from karrio.providers.aramex.utils import Settings as BaseSettings
+
+
+@attr.s(auto_attribs=True)
+class Settings(BaseSettings):
+    """Aramex connection settings."""
+
+    # Carrier specific properties
+    username: str
+    password: str
+    account_pin: str
+    account_entity: str
+    account_number: str
+    account_country_code: str
+
+    # Base properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "aramex"
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/aramex/__init__.py

@@ -0,0 +1,24 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.aramex as mappers
+# import karrio.providers.aramex.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="beta",
+    id="aramex",
+    label="Aramex",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    # options=units.OptionCode,
+    # package_presets=units.PackagePresets,
+    # packaging_types=units.PackagingType,
+    # services=units.Serives,
+    has_intl_accounts=True,
+    # New fields
+    website="https://www.aramex.com/ae/en",
+    documentation="https://www.aramex.com/us/en/developers-solution-center/aramex-apis",
+    description="Aramex is the leading global logistics provider.",
+)

karrio/providers/aramex/__init__.py

@@ -0,0 +1,24 @@
+from karrio.providers.aramex.utils import Settings
+# from karrio.providers.aramex.rate import parse_rate_response, rate_request
+# from karrio.providers.aramex.address import (
+#     parse_address_validation_response,
+#     address_validation_request
+# )
+# from karrio.providers.aramex.shipment import (
+#     parse_shipment_cancel_response,
+#     parse_shipment_response,
+#     shipment_cancel_request,
+#     shipment_request,
+# )
+# from karrio.providers.aramex.pickup import (
+#     parse_pickup_cancel_response,
+#     parse_pickup_update_response,
+#     parse_pickup_response,
+#     pickup_update_request,
+#     pickup_cancel_request,
+#     pickup_request,
+# )
+from karrio.providers.aramex.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/aramex/error.py

@@ -0,0 +1,23 @@
+from typing import List
+from karrio.schemas.aramex.tracking import Notification
+from karrio.core.utils import Element, XP
+from karrio.core.models import Message
+from karrio.providers.aramex import Settings
+
+
+def parse_error_response(response: Element, settings: Settings) -> List[Message]:
+    errors = response.xpath(".//*[local-name() = $name]", name="Notification")
+    return [_extract_error(node, settings) for node in errors]
+
+
+def _extract_error(node: Element, settings: Settings) -> Message:
+    notification = XP.to_object(Notification, node)
+
+    return Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=notification.Code,
+        message=notification.Message,
+    )

karrio/providers/aramex/tracking.py

@@ -0,0 +1,103 @@
+from typing import List, Tuple
+from functools import partial
+from karrio.schemas.aramex.array_of_string import ArrayOfstring
+from karrio.schemas.aramex.tracking import (
+    ShipmentTrackingRequest,
+    ClientInfo,
+    TrackingResult,
+)
+from karrio.core.utils import (
+    create_envelope,
+    Element,
+    Serializable,
+    XP,
+    DF,
+)
+from karrio.core.models import (
+    TrackingEvent,
+    TrackingDetails,
+    TrackingRequest,
+    Message,
+)
+from karrio.providers.aramex.utils import Settings
+from karrio.providers.aramex.error import parse_error_response
+import karrio.lib as lib
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: Settings,
+) -> Tuple[List[TrackingDetails], List[Message]]:
+    response = _response.deserialize()
+    non_existents = next(
+        (
+            XP.to_object(ArrayOfstring, n)
+            for n in lib.find_element("NonExistingWaybills", response)
+        ),
+        ArrayOfstring(),
+    )
+    results = lib.find_element("TrackingResult", response)
+    tracking_details = [_extract_detail(node, settings) for node in results]
+    errors = _extract_errors(non_existents, settings) + parse_error_response(
+        response, settings
+    )
+
+    return tracking_details, errors
+
+
+def _extract_errors(non_existents: ArrayOfstring, settings: Settings) -> List[Message]:
+    return [
+        Message(
+            carrier_name=settings.carrier_name,
+            carrier_id=settings.carrier_id,
+            message=f'Waybill "{waybill}" Not Found',
+        )
+        for waybill in non_existents.string
+    ]
+
+
+def _extract_detail(node: Element, settings: Settings) -> TrackingDetails:
+    detail = XP.to_object(TrackingResult, node)
+
+    return TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.WaybillNumber,
+        events=[
+            TrackingEvent(
+                date=DF.date(detail.UpdateDateTime, "%Y-%m-%dT%H:%M:%S"),
+                description=detail.UpdateDescription,
+                location=detail.UpdateLocation,
+                code=detail.UpdateCode,
+                time=DF.ftime(detail.UpdateDateTime, "%Y-%m-%dT%H:%M:%S"),
+            )
+        ],
+    )
+
+
+def tracking_request(payload: TrackingRequest, settings: Settings) -> Serializable:
+    request = create_envelope(
+        body_content=ShipmentTrackingRequest(
+            ClientInfo=ClientInfo(
+                UserName=settings.username,
+                Password=settings.password,
+                Version="1.0",
+                AccountNumber=settings.account_number,
+                AccountPin=settings.account_pin,
+                AccountEntity=settings.account_entity,
+                AccountCountryCode=settings.account_country_code,
+            ),
+            Transaction=None,
+            Shipments=ArrayOfstring(string=payload.tracking_numbers),
+            GetLastTrackingUpdateOnly=False,
+        )
+    )
+
+    return Serializable(
+        request,
+        partial(
+            settings.standard_request_serializer,
+            extra_namespace='xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays',
+            special_prefixes=dict(string="arr"),
+        ),
+    )

karrio/providers/aramex/units.py

@@ -0,0 +1,46 @@
+""" Aramex Native Types """
+
+# import karrio.lib as lib
+# from karrio.core.utils import Enum, Flag
+#
+# PRESET_DEFAULTS = dict(dimension_unit="CM", weight_unit="KG")
+#
+#
+# class PackagePresets(lib.Enum):
+#     # carrier_envelope = PackagePreset(
+#     #     **dict(weight=0.5, width=35.0, height=27.5, length=1.0, packaging_type="envelope"),
+#     #     **PRESET_DEFAULTS
+#     # )
+#     # carrier_box = PackagePreset(
+#     #     **dict(weight=0.5, width=35.0, height=27.5, length=1.0, packaging_type="medium_box"),
+#     #     **PRESET_DEFAULTS
+#     # )
+#     pass
+
+
+# class PackageType(lib.StrEnum):
+#     carrier_envelope = "ENVELOPE CODE"
+#     carrier_box = "BOX CODE"
+#     carrier_your_packaging = "CUSTOM PACKAGING CODE"
+#
+#     """ Unified Packaging type mapping """
+#     envelope = carrier_envelope
+#     pak = carrier_envelope
+#     tube = carrier_your_packaging
+#     pallet = carrier_your_packaging
+#     small_box = carrier_box
+#     medium_box = carrier_box
+#     large_box = carrier_box
+#     your_packaging = carrier_your_packaging
+#
+#
+# class Service(Enum):
+#     carrier_standard = "STANDARD CODE"
+#     carrier_premium = "PREMIUM CODE"
+#     carrier_overnight = "OVERNIGHT CODE"
+#
+#
+# class Option(lib.Enum):
+#     carrier_signature = "SIGNATURE CODE"
+#     carrier_saturday_delivery = "SATURDAY DELIVERY CODE"
+#     carrier_dry_ice = "DRY ICE CODE"

karrio/providers/aramex/utils.py

@@ -0,0 +1,48 @@
+from karrio.core.utils import XP, apply_namespaceprefix, Envelope, Header
+from karrio.core import Settings as BaseSettings
+
+
+class Settings(BaseSettings):
+    """Aramex connection settings."""
+
+    # Carrier specific properties
+    username: str
+    password: str
+    account_pin: str
+    account_entity: str
+    account_number: str
+    account_country_code: str
+
+    id: str = None
+    metadata: dict = {}
+
+    @property
+    def carrier_name(self):
+        return "aramex"
+
+    @property
+    def server_url(self):
+        return "http://ws.dev.aramex.net" if self.test_mode else "http://ws.aramex.net"
+
+    @staticmethod
+    def standard_request_serializer(
+        envelope: Envelope,
+        version: str = "v1",
+        extra_namespace: str = "",
+        special_prefixes: dict = None,
+    ) -> str:
+
+        namespacedef_ = (
+            f'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" '
+            f'xmlns:{version}="http://ws.aramex.net/ShippingAPI/{version}/" '
+            f"{extra_namespace}"
+        )
+        envelope.ns_prefix_ = "soap"
+        envelope.Header = Header()
+        envelope.Body.ns_prefix_ = envelope.ns_prefix_
+        envelope.Header.ns_prefix_ = envelope.ns_prefix_
+
+        for node in envelope.Body.anytypeobjs_ + envelope.Header.anytypeobjs_:
+            apply_namespaceprefix(node, version, special_prefixes)
+
+        return XP.export(envelope, namespacedef_=namespacedef_)