karrio-server-manager 2025.5rc1__py3-none-any.whl

karrio/server/manager/serializers/tracking.py

@@ -0,0 +1,250 @@
+import typing
+import logging
+from django.utils import timezone
+
+import karrio.lib as lib
+import karrio.server.serializers as serializers
+import karrio.server.core.utils as utils
+from karrio.server.core.gateway import Shipments, Carriers
+from karrio.server.core.serializers import (
+    TrackingDetails,
+    TrackingRequest,
+    ShipmentStatus,
+    TrackerStatus,
+    TrackingInfo,
+)
+
+import karrio.server.manager.models as models
+
+logger = logging.getLogger(__name__)
+DEFAULT_CARRIER_FILTER: typing.Any = dict(active=True, capability="tracking")
+
+
+@serializers.owned_model_serializer
+class TrackingSerializer(TrackingDetails):
+    carrier_id = serializers.CharField(required=False)
+    carrier_name = serializers.CharField(required=False)
+    test_mode = serializers.BooleanField(required=False)
+    options = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="additional tracking options",
+    )
+    info = TrackingInfo(
+        required=False,
+        default={},
+        help_text="The package and shipment tracking details",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="The carrier user metadata.",
+    )
+
+    def create(self, validated_data: dict, context, **kwargs) -> models.Tracking:
+        options = validated_data["options"]
+        metadata = validated_data["metadata"]
+        carrier_filter = validated_data["carrier_filter"]
+        tracking_number = validated_data["tracking_number"]
+        account_number = validated_data.get("account_number")
+        info = validated_data.get("info")
+        reference = validated_data.get("reference")
+        pending_pickup = validated_data.get("pending_pickup")
+        carrier = Carriers.first(
+            context=context,
+            **{"raise_not_found": True, **DEFAULT_CARRIER_FILTER, **carrier_filter}
+        )
+
+        response = Shipments.track(
+            TrackingRequest(
+                dict(
+                    tracking_numbers=[tracking_number],
+                    account_number=account_number,
+                    reference=reference,
+                    options=options,
+                    info=info,
+                )
+            ).data,
+            carrier=carrier,
+            raise_on_error=(pending_pickup is not True),
+        )
+
+        return models.Tracking.objects.create(
+            created_by=context.user,
+            tracking_number=tracking_number,
+            account_number=account_number,
+            events=lib.to_dict(response.tracking.events),
+            test_mode=response.tracking.test_mode,
+            delivered=response.tracking.delivered,
+            status=response.tracking.status,
+            tracking_carrier=carrier,
+            estimated_delivery=response.tracking.estimated_delivery,
+            messages=lib.to_dict(response.messages),
+            info=lib.to_dict(response.tracking.info),
+            meta=response.tracking.meta,
+            options=response.tracking.options,
+            reference=reference,
+            metadata=metadata,
+            delivery_image=getattr(response.tracking.images, "delivery_image", None),
+            signature_image=getattr(response.tracking.images, "signature_image", None),
+        )
+
+    def update(
+        self, instance: models.Tracking, validated_data: dict, context, **kwargs
+    ) -> models.Tracking:
+        last_fetch = (
+            timezone.now() - instance.updated_at
+        ).seconds / 60  # minutes since last fetch
+
+        if last_fetch >= 1 and instance.delivered is not True:
+            carrier_filter = validated_data["carrier_filter"]
+            options = {
+                instance.tracking_number: {
+                    **(instance.options.get(instance.tracking_number) or {}),
+                    **(
+                        (validated_data.get("options") or {}).get(
+                            instance.tracking_number
+                        )
+                        or {}
+                    ),
+                }
+            }
+            carrier = (
+                Carriers.first(
+                    context=context, **{**DEFAULT_CARRIER_FILTER, **carrier_filter}
+                )
+                or instance.tracking_carrier
+            )
+
+            response = Shipments.track(
+                payload=TrackingRequest(
+                    dict(tracking_numbers=[instance.tracking_number], options=options)
+                ).data,
+                carrier=carrier,
+            )
+            # update values only if changed; This is important for webhooks notification
+            changes = []
+            details = response.tracking
+            info = lib.to_dict(details.info or {})
+            events = utils.process_events(
+                response_events=details.events, current_events=instance.events
+            )
+
+            if events != instance.events:
+                instance.events = events
+                changes.append("events")
+
+            if response.messages != instance.messages:
+                instance.messages = lib.to_dict(response.messages)
+                changes.append("messages")
+
+            if details.delivered != instance.delivered:
+                instance.delivered = details.delivered
+                changes.append("delivered")
+
+            if details.status != instance.status:
+                instance.status = details.status
+                changes.append("status")
+
+            if details.estimated_delivery != instance.estimated_delivery:
+                instance.estimated_delivery = details.estimated_delivery
+                changes.append("estimated_delivery")
+
+            if details.options != instance.options:
+                instance.options = details.options
+                changes.append("options")
+
+            if any(info.keys()) and info != instance.info:
+                instance.info = serializers.process_dictionaries_mutations(
+                    ["info"], dict(info=info), instance
+                )["info"]
+                changes.append("info")
+
+            if carrier.id != instance.tracking_carrier.id:
+                instance.carrier = carrier
+                changes.append("tracking_carrier")
+
+            if details.images is not None and (
+                details.images.delivery_image != instance.delivery_image
+                or details.images.signature_image != instance.signature_image
+            ):
+                changes.append("delivery_image")
+                changes.append("signature_image")
+                instance.delivery_image = (
+                    details.images.delivery_image or instance.delivery_image
+                )
+                instance.signature_image = (
+                    details.images.signature_image or instance.signature_image
+                )
+
+            if any(changes):
+                instance.save(update_fields=changes)
+                update_shipment_tracker(instance)
+
+        return instance
+
+
+@serializers.owned_model_serializer
+class TrackerUpdateData(serializers.Serializer):
+    info = TrackingInfo(
+        required=False,
+        allow_null=True,
+        help_text="The package and shipment tracking details",
+    )
+    metadata = serializers.PlainDictField(
+        required=False, help_text="User metadata for the tracker"
+    )
+
+    def update(
+        self, instance: models.Tracking, validated_data: dict, **kwargs
+    ) -> models.Tracking:
+        changes = []
+        data = validated_data.copy()
+
+        for key, val in data.items():
+            if key in models.Tracking.DIRECT_PROPS and getattr(instance, key) != val:
+                setattr(instance, key, val)
+                changes.append(key)
+                validated_data.pop(key)
+
+        if any(changes):
+            instance.save(update_fields=changes)
+
+        return instance
+
+
+def can_mutate_tracker(
+    tracker: models.Tracking,
+    update: bool = False,
+    payload: dict = None,
+):
+    if update and tracker.delivered and [*(payload or {}).keys()] == ["metadata"]:
+        return
+
+    if update and all([key in ["metadata", "info"] for key in (payload or {}).keys()]):
+        return
+
+
+def update_shipment_tracker(tracker: models.Tracking):
+    try:
+        if tracker.status == TrackerStatus.delivered.value:
+            status = ShipmentStatus.delivered.value
+        elif tracker.status == TrackerStatus.pending.value:
+            status = tracker.shipment.status
+        elif tracker.status == TrackerStatus.out_for_delivery.value:
+            status = ShipmentStatus.out_for_delivery.value
+        elif tracker.status == TrackerStatus.delivery_failed.value:
+            status = ShipmentStatus.delivery_failed.value
+        elif tracker.status in [
+            TrackerStatus.on_hold.value,
+            TrackerStatus.delivery_delayed.value,
+        ]:
+            status = ShipmentStatus.needs_attention.value
+        else:
+            status = ShipmentStatus.in_transit.value
+
+        if tracker.shipment is not None and tracker.shipment.status != status:
+            tracker.shipment.status = status
+            tracker.shipment.save(update_fields=["status"])
+    except Exception as e:
+        logger.exception("Failed to update the tracked shipment", e)

karrio/server/manager/signals.py

@@ -0,0 +1,70 @@
+import logging
+from django.db.models import signals
+
+from karrio.server.core import utils
+import karrio.server.manager.models as models
+import karrio.server.manager.serializers as serializers
+
+logger = logging.getLogger(__name__)
+RATE_RELATED_CHANGES = [
+    # address related changes
+    "address_line1",
+    "address_line2",
+    "postal_code",
+    "city",
+    "state_province",
+    "country_code",
+    "residential",
+    # parcel related changes
+    "length",
+    "width",
+    "height",
+    "weight",
+    "weight_unit",
+    "dimension_unit",
+    "is_document",
+]
+
+
+def register_signals():
+    signals.post_save.connect(address_updated, sender=models.Address)
+    signals.post_save.connect(parcel_updated, sender=models.Parcel)
+    signals.post_delete.connect(parcel_deleted, sender=models.Parcel)
+
+    logger.info("karrio.manager signals registered...")
+
+
+@utils.disable_for_loaddata
+def address_updated(
+    sender, instance, created, raw, using, update_fields, *args, **kwargs
+):
+    """ """
+    changes = update_fields or []
+
+    if any([change in RATE_RELATED_CHANGES for change in changes]):
+        serializers.reset_related_shipment_rates(instance.shipment)
+
+
+@utils.disable_for_loaddata
+def parcel_updated(
+    sender, instance, created, raw, using, update_fields, *args, **kwargs
+):
+    """ """
+    changes = update_fields or []
+
+    if instance.reference_number is None:
+        count = models.Parcel.objects.filter(
+            **({"org__id": instance.link.org.id} if hasattr(instance, "link") else {})
+        ).count()
+
+        instance.reference_number = str(count + 1).zfill(10)
+        instance.save()
+
+    if any([change in RATE_RELATED_CHANGES for change in changes]):
+        serializers.reset_related_shipment_rates(instance.shipment)
+
+
+@utils.disable_for_loaddata
+def parcel_deleted(sender, instance, *args, **kwargs):
+    """ """
+    serializers.reset_related_shipment_rates(instance.shipment)

karrio/server/manager/tests/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+logging.disable(logging.CRITICAL)
+
+from karrio.server.manager.tests.test_addresses import *
+from karrio.server.manager.tests.test_parcels import *
+from karrio.server.manager.tests.test_shipments import *
+from karrio.server.manager.tests.test_trackers import *
+from karrio.server.manager.tests.test_custom_infos import *
+from karrio.server.manager.tests.test_pickups import *

karrio/server/manager/tests/test_addresses.py

@@ -0,0 +1,110 @@
+import json
+from unittest.mock import ANY
+from django.urls import reverse
+from rest_framework import status
+from karrio.server.core.tests import APITestCase
+from karrio.server.manager.models import Address
+
+
+class TestAddresses(APITestCase):
+    def test_create_address(self):
+        url = reverse("karrio.server.manager:address-list")
+        data = ADDRESS_DATA
+
+        response = self.client.post(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertDictEqual(response_data, ADDRESS_RESPONSE)
+
+
+class TestAddressDetails(APITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+        self.address: Address = Address.objects.create(
+            **{
+                "address_line1": "5205 rue riviera",
+                "person_name": "Old town Daniel",
+                "phone_number": "438 222 2222",
+                "city": "Montreal",
+                "country_code": "CA",
+                "postal_code": "H8Z2Z3",
+                "residential": True,
+                "state_code": "QC",
+                "validate_location": False,
+                "validation": None,
+                "created_by": self.user,
+            }
+        )
+
+    def test_update_address(self):
+        url = reverse(
+            "karrio.server.manager:address-details", kwargs=dict(pk=self.address.pk)
+        )
+        data = ADDRESS_UPDATE_DATA
+
+        response = self.client.patch(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertDictEqual(response_data, ADDRESS_UPDATE_RESPONSE)
+
+
+ADDRESS_DATA = {
+    "address_line1": "5205 rue riviera",
+    "person_name": "Old town Daniel",
+    "phone_number": "438 222 2222",
+    "city": "Montreal",
+    "country_code": "CA",
+    "postal_code": "H8Z2Z3",
+    "residential": True,
+    "state_code": "QC",
+}
+
+ADDRESS_RESPONSE = {
+    "id": ANY,
+    "object_type": "address",
+    "postal_code": "H8Z2Z3",
+    "city": "Montreal",
+    "federal_tax_id": None,
+    "state_tax_id": None,
+    "person_name": "Old town Daniel",
+    "company_name": None,
+    "country_code": "CA",
+    "email": None,
+    "phone_number": "+1 438-222-2222",
+    "state_code": "QC",
+    "street_number": None,
+    "residential": True,
+    "address_line1": "5205 rue riviera",
+    "address_line2": None,
+    "validate_location": False,
+    "validation": None,
+}
+
+ADDRESS_UPDATE_DATA = {
+    "person_name": "John Doe",
+    "company_name": "Doe corp",
+    "residential": False,
+}
+
+ADDRESS_UPDATE_RESPONSE = {
+    "id": ANY,
+    "object_type": "address",
+    "postal_code": "H8Z2Z3",
+    "city": "Montreal",
+    "federal_tax_id": None,
+    "state_tax_id": None,
+    "person_name": "John Doe",
+    "company_name": "Doe corp",
+    "country_code": "CA",
+    "email": None,
+    "phone_number": "438 222 2222",
+    "state_code": "QC",
+    "street_number": None,
+    "residential": False,
+    "address_line1": "5205 rue riviera",
+    "address_line2": None,
+    "validate_location": False,
+    "validation": None,
+}

karrio/server/manager/tests/test_custom_infos.py

@@ -0,0 +1,97 @@
+import json
+from unittest.mock import ANY
+from django.urls import reverse
+from rest_framework import status
+from karrio.server.core.tests import APITestCase
+from karrio.server.manager.models import Customs
+
+
+class TestCustomsInfo(APITestCase):
+    def test_create_customs(self):
+        url = reverse("karrio.server.manager:customs-list")
+        data = CUSTOMS_DATA
+
+        response = self.client.post(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertDictEqual(response_data, CUSTOMS_RESPONSE)
+
+
+class TestCustomsInfoDetails(APITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+        self.customs: Customs = Customs.objects.create(**{"created_by": self.user})
+
+    def test_update_customs(self):
+        url = reverse(
+            "karrio.server.manager:customs-details", kwargs=dict(pk=self.customs.pk)
+        )
+        data = CUSTOMS_UPDATE_DATA
+
+        response = self.client.patch(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertDictEqual(response_data, CUSTOMS_UPDATE_RESPONSE)
+
+
+CUSTOMS_DATA = {
+    "incoterm": "DDU",
+    "commodities": [
+        {"title": "cn", "weight": 4.0, "weight_unit": "KG", "sku": "cc"},
+    ],
+}
+
+CUSTOMS_RESPONSE = {
+    "certify": None,
+    "commercial_invoice": None,
+    "commodities": [
+        {
+            "description": None,
+            "title": "cn",
+            "id": ANY,
+            "object_type": "commodity",
+            "origin_country": None,
+            "parent_id": None,
+            "quantity": 1,
+            "metadata": {},
+            "sku": "cc",
+            "hs_code": None,
+            "value_amount": None,
+            "value_currency": None,
+            "weight": 4.0,
+            "weight_unit": "KG",
+        }
+    ],
+    "content_description": None,
+    "content_type": None,
+    "duty": None,
+    "duty_billing_address": None,
+    "id": ANY,
+    "object_type": "customs_info",
+    "incoterm": "DDU",
+    "invoice": None,
+    "invoice_date": None,
+    "options": {},
+    "signer": None,
+}
+
+CUSTOMS_UPDATE_DATA = {"incoterm": "DDP"}
+
+CUSTOMS_UPDATE_RESPONSE = {
+    "certify": None,
+    "commercial_invoice": None,
+    "commodities": [],
+    "content_description": None,
+    "content_type": None,
+    "duty": None,
+    "duty_billing_address": None,
+    "id": ANY,
+    "object_type": "customs_info",
+    "incoterm": "DDP",
+    "invoice": None,
+    "invoice_date": None,
+    "options": {},
+    "signer": None,
+}

karrio/server/manager/tests/test_parcels.py

@@ -0,0 +1,104 @@
+import json
+from unittest.mock import ANY
+from django.urls import reverse
+from rest_framework import status
+from karrio.server.core.tests import APITestCase
+from karrio.server.manager.models import Parcel
+
+
+class TestParcels(APITestCase):
+    def test_create_parcel(self):
+        url = reverse("karrio.server.manager:parcel-list")
+        data = PARCEL_DATA
+
+        response = self.client.post(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertDictEqual(response_data, PARCEL_RESPONSE)
+
+
+class TestParcelDetails(APITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+        self.parcel: Parcel = Parcel.objects.create(
+            **{
+                "weight": 1,
+                "width": 20,
+                "height": 10,
+                "length": 29,
+                "weight_unit": "KG",
+                "dimension_unit": "CM",
+                "created_by": self.user,
+            }
+        )
+
+    def test_update_parcel(self):
+        url = reverse(
+            "karrio.server.manager:parcel-details", kwargs=dict(pk=self.parcel.pk)
+        )
+        data = PARCEL_UPDATE_DATA
+
+        response = self.client.patch(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertDictEqual(response_data, PARCEL_UPDATE_RESPONSE)
+
+
+PARCEL_DATA = {
+    "weight": 1,
+    "width": 20,
+    "height": 10,
+    "length": 29,
+    "weight_unit": "KG",
+    "dimension_unit": "CM",
+}
+
+PARCEL_RESPONSE = {
+    "id": ANY,
+    "object_type": "parcel",
+    "weight": 1.0,
+    "width": 20.0,
+    "height": 10.0,
+    "length": 29.0,
+    "packaging_type": None,
+    "package_preset": None,
+    "description": None,
+    "content": None,
+    "is_document": False,
+    "items": [],
+    "weight_unit": "KG",
+    "dimension_unit": "CM",
+    "freight_class": None,
+    "reference_number": ANY,
+    "options": {},
+}
+
+PARCEL_UPDATE_DATA = {
+    "width": 5.0,
+    "height": 4.5,
+    "length": 10.0,
+    "weight_unit": "LB",
+    "dimension_unit": "IN",
+}
+
+PARCEL_UPDATE_RESPONSE = {
+    "id": ANY,
+    "object_type": "parcel",
+    "weight": 1.0,
+    "width": 5.0,
+    "height": 4.5,
+    "length": 10.0,
+    "packaging_type": None,
+    "package_preset": None,
+    "description": None,
+    "content": None,
+    "is_document": False,
+    "items": [],
+    "weight_unit": "LB",
+    "dimension_unit": "IN",
+    "freight_class": None,
+    "reference_number": ANY,
+    "options": {},
+}