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

karrio/server/manager/tests/test_trackers.py

@@ -0,0 +1,215 @@
+import json
+from time import sleep
+from django.urls import reverse
+from rest_framework import status
+from unittest.mock import patch, ANY
+from karrio.core.models import TrackingDetails, TrackingEvent
+from karrio.server.core.tests import APITestCase
+import karrio.server.manager.models as models
+
+
+class TestTrackers(APITestCase):
+    def test_shipment_tracking(self):
+        url = reverse(
+            "karrio.server.manager:shipment-tracker",
+            kwargs=dict(tracking_number="1Z12345E6205277936", carrier_name="ups"),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = RETURNED_VALUE
+            response = self.client.get(f"{url}")
+            response_data = json.loads(response.content)
+
+            self.assertResponseNoErrors(response)
+            self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+            self.assertDictEqual(response_data, TRACKING_RESPONSE)
+
+    def test_shipment_tracking_retry(self):
+        url = reverse(
+            "karrio.server.manager:shipment-tracker",
+            kwargs=dict(tracking_number="1Z12345E6205277936", carrier_name="ups"),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = RETURNED_VALUE
+            self.client.get(f"{url}")
+            sleep(0.1)
+            response = self.client.get(f"{url}")
+            response_data = json.loads(response.content)
+
+        self.assertResponseNoErrors(response)
+        self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+        self.assertDictEqual(response_data, TRACKING_RESPONSE)
+        self.assertEqual(len(self.user.tracking_set.all()), 1)
+
+
+class TestTrackersUpdate(APITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+        self.tracker = models.Tracking.objects.create(
+            **{
+                "tracking_number": "00340434292135100124",
+                "test_mode": True,
+                "delivered": False,
+                "events": [
+                    {
+                        "date": "2021-01-11",
+                        "description": "The instruction data for this shipment have been provided by the sender to DHL electronically",
+                        "location": "BONN",
+                        "code": "pre-transit",
+                        "time": "20:34",
+                    }
+                ],
+                "status": "in_transit",
+                "created_by": self.user,
+                "tracking_carrier": self.dhl_carrier,
+                "info": {
+                    "carrier_tracking_link": "https://www.dhl.com/ca-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434292135100124",
+                    "package_weight": 0.74,
+                    "package_weight_unit": "KG",
+                    "shipping_date": "2021-01-11",
+                },
+            }
+        )
+
+    def test_update_tracker_info(self):
+        url = reverse(
+            "karrio.server.manager:tracker-details",
+            kwargs=dict(id_or_tracking_number=self.tracker.pk),
+        )
+        data = dict(info=TRACKING_INFO)
+
+        response = self.client.put(url, data)
+        response_data = json.loads(response.content)
+
+        self.assertResponseNoErrors(response)
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertDictEqual(response_data, UPDATE_TRACKING_RESPONSE)
+
+
+RETURNED_VALUE = (
+    [
+        TrackingDetails(
+            carrier_id="ups_package",
+            carrier_name="ups",
+            tracking_number="1Z12345E6205277936",
+            delivered=False,
+            events=[
+                TrackingEvent(
+                    code="KB",
+                    date="2010-08-30",
+                    description="UPS INTERNAL ACTIVITY CODE",
+                    location="BONN",
+                    time="10:39",
+                )
+            ],
+        )
+    ],
+    [],
+)
+
+TRACKING_RESPONSE = {
+    "id": ANY,
+    "object_type": "tracker",
+    "carrier_id": "ups_package",
+    "carrier_name": "ups",
+    "tracking_number": "1Z12345E6205277936",
+    "test_mode": True,
+    "delivered": False,
+    "status": "in_transit",
+    "estimated_delivery": ANY,
+    "delivery_image_url": None,
+    "signature_image_url": None,
+    "events": [
+        {
+            "code": "KB",
+            "date": "2010-08-30",
+            "description": "UPS INTERNAL ACTIVITY CODE",
+            "location": "BONN",
+            "time": "10:39",
+            "latitude": None,
+            "longitude": None,
+        }
+    ],
+    "messages": [],
+    "meta": {
+        "ext": "ups",
+        "carrier": "ups",
+    },
+    "metadata": {},
+    "info": {
+        "carrier_tracking_link": "https://www.ups.com/track?loc=en_US&requester=QUIC&tracknum=1Z12345E6205277936/trackdetails",
+        "customer_name": None,
+        "expected_delivery": None,
+        "note": None,
+        "order_date": None,
+        "order_id": None,
+        "package_weight": None,
+        "package_weight_unit": None,
+        "shipment_delivery_date": None,
+        "shipment_destination_country": None,
+        "shipment_destination_postal_code": None,
+        "shipment_origin_country": None,
+        "shipment_origin_postal_code": None,
+        "shipment_package_count": None,
+        "shipment_pickup_date": None,
+        "shipment_service": None,
+        "shipping_date": None,
+        "signed_by": None,
+        "source": "api",
+    },
+}
+
+TRACKING_INFO = {
+    "shipment_service": "dhl_express_worldwide",
+    "signed_by": "Jane Doe",
+}
+
+UPDATE_TRACKING_RESPONSE = {
+    "id": ANY,
+    "object_type": "tracker",
+    "carrier_name": "dhl_express",
+    "carrier_id": "dhl_express",
+    "tracking_number": "00340434292135100124",
+    "events": [
+        {
+            "date": "2021-01-11",
+            "description": "The instruction data for this shipment have been provided by the sender to DHL electronically",
+            "code": "pre-transit",
+            "latitude": None,
+            "location": "BONN",
+            "longitude": None,
+            "time": "20:34",
+        }
+    ],
+    "delivered": False,
+    "test_mode": True,
+    "status": "in_transit",
+    "estimated_delivery": ANY,
+    "delivery_image_url": None,
+    "signature_image_url": None,
+    "messages": [],
+    "meta": {},
+    "metadata": {},
+    "info": {
+        "carrier_tracking_link": "https://www.dhl.com/ca-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434292135100124",
+        "customer_name": None,
+        "expected_delivery": None,
+        "note": None,
+        "order_date": None,
+        "order_id": None,
+        "package_weight": "0.74",
+        "package_weight_unit": "KG",
+        "shipment_delivery_date": None,
+        "shipment_destination_country": None,
+        "shipment_destination_postal_code": None,
+        "shipment_origin_country": None,
+        "shipment_origin_postal_code": None,
+        "shipment_package_count": None,
+        "shipment_pickup_date": None,
+        "shipment_service": "dhl_express_worldwide",
+        "shipping_date": "2021-01-11",
+        "signed_by": "Jane Doe",
+        "source": None,
+    },
+}

karrio/server/manager/urls.py

@@ -0,0 +1,10 @@
+"""
+karrio server manager module urls
+"""
+from django.urls import include, path
+from karrio.server.manager.views import router
+
+app_name = "karrio.server.manager"
+urlpatterns = [
+    path("v1/", include(router.urls)),
+]

karrio/server/manager/views/__init__.py

@@ -0,0 +1,9 @@
+import karrio.server.manager.views.addresses
+import karrio.server.manager.views.parcels
+import karrio.server.manager.views.shipments
+import karrio.server.manager.views.trackers
+import karrio.server.manager.views.customs
+import karrio.server.manager.views.pickups
+import karrio.server.manager.views.documents
+import karrio.server.manager.views.manifests
+from karrio.server.manager.router import router

karrio/server/manager/views/addresses.py

@@ -0,0 +1,154 @@
+import logging
+
+from django.urls import path
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.pagination import LimitOffsetPagination
+
+from karrio.server.core.views.api import GenericAPIView, APIView
+from karrio.server.manager.serializers import (
+    PaginatedResult,
+    ErrorResponse,
+    AddressData,
+    Address,
+    AddressSerializer,
+    can_mutate_address,
+)
+from karrio.server.manager.router import router
+import karrio.server.manager.models as models
+import karrio.server.openapi as openapi
+
+
+ENDPOINT_ID = "$"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+logger = logging.getLogger(__name__)
+Addresses = PaginatedResult("AddressList", Address)
+
+
+class AddressList(GenericAPIView):
+    queryset = models.Address.objects
+    pagination_class = type(
+        "CustomPagination", (LimitOffsetPagination,), dict(default_limit=20)
+    )
+    serializer_class = Addresses
+
+    @openapi.extend_schema(
+        tags=["Addresses"],
+        operation_id=f"{ENDPOINT_ID}list",
+        extensions={"x-operationId": "listAddresses"},
+        summary="List all addresses",
+        responses={
+            200: Addresses(),
+            404: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, request: Request):
+        """
+        Retrieve all addresses.
+        """
+        addresses = models.Address.access_by(request).filter(
+            **{
+                f"{prop}__isnull": True
+                for prop in models.Address.HIDDEN_PROPS
+                if prop != "org"
+            }
+        )
+        response = self.paginate_queryset(Address(addresses, many=True).data)
+        return self.get_paginated_response(response)
+
+    @openapi.extend_schema(
+        tags=["Addresses"],
+        operation_id=f"{ENDPOINT_ID}create",
+        extensions={"x-operationId": "createAddress"},
+        summary="Create an address",
+        request=AddressData(),
+        responses={
+            201: Address(),
+            400: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def post(self, request: Request):
+        """
+        Create a new address.
+        """
+        address = (
+            AddressSerializer.map(data=request.data, context=request).save().instance
+        )
+        return Response(Address(address).data, status=status.HTTP_201_CREATED)
+
+
+class AddressDetail(APIView):
+
+    @openapi.extend_schema(
+        tags=["Addresses"],
+        operation_id=f"{ENDPOINT_ID}retrieve",
+        extensions={"x-operationId": "retrieveAddress"},
+        summary="Retrieve an address",
+        responses={
+            200: Address(),
+            400: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, request: Request, pk: str):
+        """
+        Retrieve an address.
+        """
+        address = models.Address.access_by(request).get(pk=pk)
+        return Response(Address(address).data)
+
+    @openapi.extend_schema(
+        tags=["Addresses"],
+        operation_id=f"{ENDPOINT_ID}update",
+        extensions={"x-operationId": "updateAddress"},
+        summary="Update an address",
+        request=AddressData(),
+        responses={
+            200: Address(),
+            400: ErrorResponse(),
+            404: ErrorResponse(),
+            409: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def patch(self, request: Request, pk: str):
+        """
+        update an address.
+        """
+        address = models.Address.access_by(request).get(pk=pk)
+        can_mutate_address(address, update=True)
+
+        AddressSerializer.map(address, data=request.data).save()
+
+        return Response(Address(address).data)
+
+    @openapi.extend_schema(
+        tags=["Addresses"],
+        operation_id=f"{ENDPOINT_ID}discard",
+        extensions={"x-operationId": "discardAddress"},
+        summary="Discard an address",
+        responses={
+            200: Address(),
+            404: ErrorResponse(),
+            409: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def delete(self, request: Request, pk: str):
+        """
+        Discard an address.
+        """
+        address = models.Address.access_by(request).get(pk=pk)
+        can_mutate_address(address, update=True, delete=True)
+
+        address.delete(keep_parents=True)
+
+        return Response(Address(address).data)
+
+
+router.urls.append(path("addresses", AddressList.as_view(), name="address-list"))
+router.urls.append(
+    path("addresses/<str:pk>", AddressDetail.as_view(), name="address-details")
+)

karrio/server/manager/views/customs.py

@@ -0,0 +1,159 @@
+import logging
+
+from django.urls import path
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.pagination import LimitOffsetPagination
+
+from karrio.server.core.views.api import GenericAPIView, APIView
+from karrio.server.manager.serializers import (
+    PaginatedResult,
+    ErrorResponse,
+    CustomsData,
+    Customs,
+    CustomsSerializer,
+    can_mutate_customs,
+)
+from karrio.server.manager.router import router
+import karrio.server.manager.models as models
+import karrio.server.openapi as openapi
+
+ENDPOINT_ID = "$$"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+logger = logging.getLogger(__name__)
+CustomsInfoList = PaginatedResult("CustomsList", Customs)
+
+
+class CustomsList(GenericAPIView):
+    queryset = models.Customs.objects
+    pagination_class = type(
+        "CustomPagination", (LimitOffsetPagination,), dict(default_limit=20)
+    )
+    serializer_class = CustomsInfoList
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Customs"],
+        operation_id=f"{ENDPOINT_ID}list",
+        extensions={"x-operationId": "listCustomsInfo"},
+        summary="List all customs info",
+        responses={
+            200: CustomsInfoList(),
+            404: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, request: Request):
+        """
+        Retrieve all stored customs declarations.
+        """
+        customs_info = models.Customs.access_by(request).filter(
+            **{
+                f"{prop}__isnull": True
+                for prop in models.Customs.HIDDEN_PROPS
+                if prop != "org"
+            }
+        )
+        serializer = Customs(customs_info, many=True)
+        response = self.paginate_queryset(serializer.data)
+        return self.get_paginated_response(response)
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Customs"],
+        operation_id=f"{ENDPOINT_ID}create",
+        extensions={"x-operationId": "createCustomsInfo"},
+        summary="Create a customs info",
+        request=CustomsData(),
+        responses={
+            201: Customs(),
+            400: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def post(self, request: Request):
+        """
+        Create a new customs declaration.
+        """
+        customs = (
+            CustomsSerializer.map(data=request.data, context=request).save().instance
+        )
+        return Response(Customs(customs).data, status=status.HTTP_201_CREATED)
+
+
+class CustomsDetail(APIView):
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Customs"],
+        operation_id=f"{ENDPOINT_ID}retrieve",
+        extensions={"x-operationId": "retrieveCustomsInfo"},
+        summary="Retrieve a customs info",
+        responses={
+            200: Customs(),
+            404: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, request: Request, pk: str):
+        """
+        Retrieve customs declaration.
+        """
+        address = models.Customs.access_by(request).get(pk=pk)
+        return Response(Customs(address).data)
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Customs"],
+        operation_id=f"{ENDPOINT_ID}update",
+        extensions={"x-operationId": "updateCustomsInfo"},
+        summary="Update a customs info",
+        request=CustomsData(),
+        responses={
+            200: Customs(),
+            400: ErrorResponse(),
+            404: ErrorResponse(),
+            409: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def patch(self, request: Request, pk: str):
+        """
+        modify an existing customs declaration.
+        """
+        customs = models.Customs.access_by(request).get(pk=pk)
+        can_mutate_customs(customs)
+
+        CustomsSerializer.map(customs, data=request.data, context=request).save()
+
+        return Response(Customs(customs).data)
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Customs"],
+        operation_id=f"{ENDPOINT_ID}discard",
+        extensions={"x-operationId": "discardCustomsInfo"},
+        summary="Discard a customs info",
+        responses={
+            200: Customs(),
+            404: ErrorResponse(),
+            409: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def delete(self, request: Request, pk: str):
+        """
+        Discard a customs declaration.
+        """
+        customs = models.Customs.access_by(request).get(pk=pk)
+        can_mutate_customs(customs)
+
+        customs.delete(keep_parents=True)
+
+        return Response(Customs(customs).data)
+
+
+router.urls.append(path("customs_info", CustomsList.as_view(), name="customs-list"))
+router.urls.append(
+    path("customs_info/<str:pk>", CustomsDetail.as_view(), name="customs-details")
+)

karrio/server/manager/views/documents.py

@@ -0,0 +1,131 @@
+import logging
+from django.urls import path
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.pagination import LimitOffsetPagination
+from django_filters.rest_framework import DjangoFilterBackend
+
+from karrio.server.core.views.api import GenericAPIView, APIView
+from karrio.server.core.filters import UploadRecordFilter
+from karrio.server.manager.router import router
+from karrio.server.manager.serializers import (
+    ErrorResponse,
+    ErrorMessages,
+    PaginatedResult,
+    DocumentUploadData,
+    DocumentUploadRecord,
+    DocumentUploadSerializer,
+    can_upload_shipment_document,
+)
+import karrio.server.manager.models as models
+import karrio.server.openapi as openapi
+
+ENDPOINT_ID = "$$$$$&"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+logger = logging.getLogger(__name__)
+DocumentUploadRecords = PaginatedResult("DocumentUploadRecords", DocumentUploadRecord)
+
+
+class DocumentList(GenericAPIView):
+    pagination_class = type(
+        "CustomPagination", (LimitOffsetPagination,), dict(default_limit=20)
+    )
+    filter_backends = (DjangoFilterBackend,)
+    filterset_class = UploadRecordFilter
+    serializer_class = DocumentUploadRecords
+    model = models.DocumentUploadRecord
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}uploads",
+        summary="List all upload records",
+        parameters=UploadRecordFilter.parameters,
+        responses={
+            200: DocumentUploadRecords(),
+            404: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, _: Request):
+        """
+        Retrieve all shipping document upload records.
+        """
+        upload_records = self.filter_queryset(self.get_queryset())
+        response = self.paginate_queryset(
+            DocumentUploadRecord(upload_records, many=True).data
+        )
+
+        return self.get_paginated_response(response)
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}upload",
+        summary="Upload documents",
+        responses={
+            201: DocumentUploadRecord(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+        request=DocumentUploadData(),
+    )
+    def post(self, request: Request):
+        """Upload a shipping document."""
+        shipment = (
+            models.Shipment.access_by(request)
+            .filter(
+                pk=request.data.get("shipment_id"),
+                selected_rate_carrier__isnull=False,
+            )
+            .first()
+        )
+
+        can_upload_shipment_document(shipment)
+
+        upload_record = (
+            DocumentUploadSerializer.map(
+                getattr(shipment, "shipment_upload_record", None),
+                data=request.data,
+                context=request,
+            )
+            .save(shipment=shipment)
+            .instance
+        )
+
+        return Response(
+            DocumentUploadRecord(upload_record).data, status=status.HTTP_201_CREATED
+        )
+
+
+class DocumentDetails(APIView):
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}retrieve_upload",
+        summary="Retrieve upload record",
+        responses={
+            200: DocumentUploadRecord(),
+            404: ErrorResponse(),
+            500: ErrorResponse(),
+        },
+    )
+    def get(self, request: Request, pk: str):
+        """Retrieve a shipping document upload record."""
+        upload_record = models.UploadRecord.access_by(request).get(pk=pk)
+
+        return Response(DocumentUploadRecord(upload_record).data)
+
+
+router.urls.append(
+    path(
+        "documents/uploads",
+        DocumentList.as_view(),
+        name="document-upload-list",
+    )
+)
+router.urls.append(
+    path(
+        "documents/uploads/<str:pk>",
+        DocumentDetails.as_view(),
+        name="document-upload-details",
+    )
+)