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

karrio/server/providers/views/carriers.py

@@ -0,0 +1,269 @@
+import io
+import base64
+import logging
+import re
+from django.http import JsonResponse
+from django.urls import path, re_path
+from rest_framework import status, views
+from rest_framework.request import Request
+from rest_framework.response import Response
+from django.core.files.base import ContentFile
+from django_downloadview import VirtualDownloadView
+
+import karrio.lib as lib
+import karrio.server.openapi as openapi
+import karrio.server.samples as samples
+import karrio.server.core.views.api as api
+import karrio.server.providers.models as models
+from karrio.server.core import datatypes, dataunits, serializers
+
+logger = logging.getLogger(__name__)
+ENDPOINT_ID = "&&"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+
+
+class CarrierList(views.APIView):
+    permission_classes = []
+
+    @openapi.extend_schema(
+        auth=[],
+        tags=["Carriers"],
+        operation_id=f"{ENDPOINT_ID}list",
+        extensions={"x-operationId": "listCarriers"},
+        summary="List all carriers",
+        responses={
+            200: serializers.CarrierDetails(many=True),
+            500: serializers.ErrorResponse(),
+        },
+        examples=[
+            openapi.OpenApiExample(
+                name="Carrier List",
+                value=lib.to_dict(samples.CARRIER_DETAILS_SAMPLE),
+            )
+        ],
+    )
+    def get(self, request: Request):
+        """Returns the list of configured carriers"""
+        references = dataunits.contextual_reference(reduced=False)
+        carriers = [
+            dataunits.get_carrier_details(
+                carrier_name,
+                contextual_reference=references,
+            )
+            for carrier_name in references["carriers"].keys()
+        ]
+
+        return Response(carriers, status=status.HTTP_200_OK)
+
+
+class CarrierDetails(api.APIView):
+    permission_classes = []
+
+    @openapi.extend_schema(
+        auth=[],
+        tags=["Carriers"],
+        operation_id=f"{ENDPOINT_ID}get_details",
+        extensions={"x-operationId": "getDetails"},
+        summary="Get carrier details",
+        parameters=[
+            openapi.OpenApiParameter(
+                "carrier_name",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                description=(
+                    "The unique carrier slug. <br/>"
+                    f"Values: {', '.join([f'`{c}`' for c in dataunits.CARRIER_NAMES])}"
+                ),
+            )
+        ],
+        responses={
+            200: serializers.CarrierDetails(),
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def get(self, request: Request, carrier_name: str):
+        """
+        Retrieve a carrier's details
+        """
+        references = dataunits.contextual_reference(reduced=False)
+
+        if carrier_name not in references["carriers"]:
+            raise Exception(f"Unknown carrier: {carrier_name}")
+
+        carrier_details = dataunits.get_carrier_details(
+            carrier_name,
+            contextual_reference=references,
+        )
+
+        return Response(carrier_details, status=status.HTTP_200_OK)
+
+
+class CarrierServices(api.APIView):
+    permission_classes = []
+
+    @openapi.extend_schema(
+        auth=[],
+        tags=["Carriers"],
+        operation_id=f"{ENDPOINT_ID}get_services",
+        extensions={"x-operationId": "getServices"},
+        summary="Get carrier services",
+        parameters=[
+            openapi.OpenApiParameter(
+                "carrier_name",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                description=(
+                    "The unique carrier slug. <br/>"
+                    f"Values: {', '.join([f'`{c}`' for c in dataunits.CARRIER_NAMES])}"
+                ),
+            )
+        ],
+        responses={
+            200: openapi.OpenApiTypes.OBJECT,
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+        examples=[
+            openapi.OpenApiExample(
+                name="Carrier List",
+                value=lib.to_dict(samples.CARRIER_SERICES_SAMPLE),
+            )
+        ],
+    )
+    def get(self, request: Request, carrier_name: str):
+        """
+        Retrieve a carrier's services
+        """
+        references = dataunits.contextual_reference()
+
+        if carrier_name not in references["carriers"]:
+            raise Exception(f"Unknown carrier: {carrier_name}")
+
+        services = references["services"].get(carrier_name, {})
+
+        return Response(services, status=status.HTTP_200_OK)
+
+
+class CarrierOptions(api.APIView):
+    permission_classes = []
+
+    @openapi.extend_schema(
+        auth=[],
+        tags=["Carriers"],
+        operation_id=f"{ENDPOINT_ID}get_options",
+        extensions={"x-operationId": "getOptions"},
+        summary="Get carrier options",
+        parameters=[
+            openapi.OpenApiParameter(
+                "carrier_name",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                description=(
+                    "The unique carrier slug. <br/>"
+                    f"Values: {', '.join([f'`{c}`' for c in dataunits.CARRIER_NAMES])}"
+                ),
+            )
+        ],
+        responses={
+            200: openapi.OpenApiTypes.OBJECT,
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+        examples=[
+            openapi.OpenApiExample(
+                name="Carrier Options",
+                value=lib.to_dict(samples.CARRIER_OPTIONS_SAMPLE),
+            )
+        ],
+    )
+    def get(self, request: Request, carrier_name: str):
+        """
+        Retrieve a carrier's options
+        """
+        references = dataunits.contextual_reference()
+
+        if carrier_name not in references["carriers"]:
+            raise Exception(f"Unknown carrier: {carrier_name}")
+
+        options = references["options"].get(carrier_name, {})
+
+        return Response(options, status=status.HTTP_200_OK)
+
+
+class CarrierLabelPreview(VirtualDownloadView):
+    def get(
+        self,
+        request: Request,
+        pk: str,
+        format: str = "pdf",
+        **kwargs,
+    ):
+        """
+        Preview a carrier label template...
+        """
+        try:
+            query_params = request.GET.dict()
+            carrier = models.Carrier.objects.get(carrier_code="generic", pk=pk)
+
+            self.document = self._generate_label(carrier, format)
+            self.name = f"{carrier.custom_carrier_name}_label.{format}"
+            self.attachment = query_params.get("download", False)
+
+            response = super(CarrierLabelPreview, self).get(
+                request, pk, format, **kwargs
+            )
+            response["X-Frame-Options"] = "ALLOWALL"
+            return response
+        except Exception as e:
+            return JsonResponse(dict(error=str(e)), status=status.HTTP_409_CONFLICT)
+
+    def get_file(self):
+        content = base64.b64decode(self.document or "")
+        buffer = io.BytesIO()
+        buffer.write(content)
+
+        return ContentFile(buffer.getvalue(), name=self.name)
+
+    def _generate_label(self, carrier, format):
+        import karrio.sdk as karrio
+        import karrio.providers.generic.units as units
+
+        template = carrier.label_template
+        data = lib.identity(
+            template.shipment_sample
+            if template is not None and len(template.shipment_sample.items()) > 0
+            else units.SAMPLE_SHIPMENT_REQUEST
+        )
+        service = lib.identity(
+            data.get("service") or next((s.service_code for s in carrier.services))
+        )
+        request = lib.to_object(
+            datatypes.ShipmentRequest,
+            {
+                **data,
+                "service": service,
+                "label_type": format.upper(),
+                "selected_rate_id": data.get("selected_rate_id") or "",
+                "rates": data.get("rates") or [],
+            },
+        )
+
+        shipment, _ = karrio.Shipment.create(request).from_(carrier.gateway).parse()
+
+        if shipment is None:
+            raise Exception("Failed to generate label")
+
+        return shipment.docs.label
+
+
+urlpatterns = [
+    path("carriers", CarrierList.as_view(), name="carrier-list"),
+    path("carriers/<str:carrier_name>", CarrierDetails.as_view(), name="carrier-details"),
+    path("carriers/<str:carrier_name>/services", CarrierServices.as_view(), name="carrier-services"),
+    path("carriers/<str:carrier_name>/options", CarrierOptions.as_view(), name="carrier-options"),
+    re_path(
+        r"^carriers/(?P<pk>\w+)/label.(?P<format>[a-z0-9]+)",
+        CarrierLabelPreview.as_view(),
+        name="carrier-label",
+    ),
+]

karrio/server/providers/views/connections.py

@@ -0,0 +1,176 @@
+import logging
+import django.urls as urls
+import rest_framework.status as status
+import rest_framework.request as request
+import rest_framework.response as response
+import django_filters.rest_framework as drf
+import rest_framework.pagination as pagination
+
+import karrio.lib as lib
+import karrio.server.openapi as openapi
+import karrio.server.core.views.api as api
+import karrio.server.core.filters as filters
+import karrio.server.core.gateway as gateway
+import karrio.server.providers.models as models
+import karrio.server.providers.serializers as serializers
+
+logger = logging.getLogger(__name__)
+ENDPOINT_ID = "&&&"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+CarrierConnectionList = serializers.PaginatedResult(
+    "CarrierConnectionList", serializers.CarrierConnection
+)
+
+
+class CarrierConnectionListView(api.GenericAPIView):
+    model = models.Carrier
+    serializer_class = serializers.CarrierConnection
+    filterset_class = filters.CarrierConnectionFilter
+    filter_backends = (drf.DjangoFilterBackend,)
+    pagination_class = type(
+        "CustomPagination",
+        (pagination.LimitOffsetPagination,),
+        dict(default_limit=20),
+    )
+
+    @openapi.extend_schema(
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}list",
+        extensions={"x-operationId": "listCarrierConnections"},
+        summary="List carrier connections",
+        responses={
+            200: CarrierConnectionList(),
+            400: serializers.ErrorResponse(),
+        },
+        parameters=filters.CarrierConnectionFilter.parameters,
+    )
+    def get(self, request: request.Request):
+        """Retrieve all carrier connections"""
+        filter = {
+            **filters.CarrierFilters(request.query_params).to_dict(),
+            "context": request,
+        }
+
+        # fmt: off
+        connections = gateway.Carriers.list(**filter)
+        response = self.paginate_queryset(
+            [
+                {
+                    **_,
+                    "metadata": None if _["is_system"] else _["metadata"],
+                    "credentials": None if _["is_system"] else _["credentials"]
+                }
+                for _ in serializers.CarrierConnection(connections, many=True).data
+            ]
+        )
+        # fmt: on
+
+        return self.get_paginated_response(response)
+
+    @openapi.extend_schema(
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}add",
+        extensions={"x-operationId": "addCarrierConnection"},
+        summary="Add a carrier connection",
+        responses={
+            201: serializers.CarrierConnection(),
+            400: serializers.ErrorResponse(),
+            424: serializers.ErrorMessages(),
+            500: serializers.ErrorResponse(),
+        },
+        request=serializers.CarrierConnectionData(),
+    )
+    def post(self, request: request.Request):
+        """Add a new carrier connection."""
+        connection = lib.identity(
+            serializers.CarrierConnectionModelSerializer.map(
+                data=serializers.CarrierConnectionData.map(data=request.data).data,
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        return response.Response(
+            serializers.CarrierConnection(connection).data,
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class CarrierConnectionDetail(api.APIView):
+    @openapi.extend_schema(
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}retrieve",
+        extensions={"x-operationId": "retrieveCarrierConnection"},
+        summary="Retrieve a connection",
+        responses={
+            200: serializers.CarrierConnection(),
+            400: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def get(self, request: request.Request, pk: str):
+        """Retrieve carrier connection."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+        return response.Response(serializers.CarrierConnection(connection).data)
+
+    @openapi.extend_schema(
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}update",
+        extensions={"x-operationId": "updateCarrierConnection"},
+        summary="Update a connection",
+        request=serializers.CarrierConnectionData(),
+        responses={
+            200: serializers.CarrierConnection(),
+            400: serializers.ErrorResponse(),
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def patch(self, request: request.Request, pk: str):
+        """Update a carrier connection."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+        update = lib.identity(
+            serializers.CarrierConnectionModelSerializer.map(
+                connection,
+                data=request.data,
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        return response.Response(serializers.CarrierConnection(update).data)
+
+    @openapi.extend_schema(
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}remove",
+        extensions={"x-operationId": "removeCarrierConnection"},
+        summary="Remove a carrier connection",
+        responses={
+            200: serializers.CarrierConnection(),
+            404: serializers.ErrorResponse(),
+            409: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def delete(self, request: request.Request, pk: str):
+        """Remove a carrier connection."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+
+        connection.delete(keep_parents=True)
+
+        return response.Response(serializers.CarrierConnection(connection).data)
+
+
+urlpatterns = [
+    urls.path(
+        "connections",
+        CarrierConnectionListView.as_view(),
+        name="carrier-connection-list",
+    ),
+    urls.path(
+        "connections/<str:pk>",
+        CarrierConnectionDetail.as_view(),
+        name="carrier-connection-details",
+    ),
+]