karrio-server-documents 2025.5.2__py3-none-any.whl

karrio/server/documents/views/printers.py

@@ -0,0 +1,223 @@
+import io
+import sys
+import base64
+from django.urls import re_path
+from django.utils import timezone
+from django.http import JsonResponse
+from django.core.files.base import ContentFile
+from django_downloadview import VirtualDownloadView
+from rest_framework import status
+
+import karrio.lib as lib
+import karrio.server.openapi as openapi
+import karrio.server.documents.models as models
+import karrio.server.documents.generator as generator
+from karrio.server.core.logging import logger
+from karrio.server.core.utils import validate_resource_token
+
+
+class TemplateDocsPrinter(VirtualDownloadView):
+    def get(self, request, pk: str, slug: str, **kwargs):
+        """Generate a document from template."""
+        error = validate_resource_token(request, "template", [pk], "render")
+        if error:
+            return error
+
+        try:
+            template = models.DocumentTemplate.objects.get(pk=pk, slug=slug)
+            query_params = request.GET.dict()
+
+            self.document = generator.Documents.generate_template(
+                template, query_params, context=request
+            )
+            self.name = f"{slug}.pdf"
+            self.attachment = "download" in query_params
+
+            response = super().get(request, pk, slug, **kwargs)
+            response["X-Frame-Options"] = "ALLOWALL"
+            return response
+        except Exception as e:
+            logger.exception(
+                "Template document generation failed",
+                template_id=pk,
+                template_slug=slug,
+                error=str(e),
+            )
+            _, __, exc_traceback = sys.exc_info()
+            trace = exc_traceback
+            while trace and trace.tb_next:
+                trace = trace.tb_next
+                if "<template>" in str(trace.tb_frame):
+                    break
+
+            return JsonResponse(
+                dict(error=str(e), line=getattr(trace, "tb_lineno", None)),
+                status=status.HTTP_409_CONFLICT,
+            )
+
+    def get_file(self):
+        return ContentFile(self.document.getvalue(), name=self.name)
+
+
+class ShipmentDocsPrinter(VirtualDownloadView):
+    @openapi.extend_schema(exclude=True)
+    def get(self, request, doc: str = "label", format: str = "pdf", **kwargs):
+        """Retrieve batch shipment labels or invoices."""
+        from karrio.server.manager.models import Shipment
+
+        if doc not in ["label", "invoice"]:
+            return JsonResponse(
+                dict(error=f"Invalid document type: {doc}"),
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        resource_ids = request.GET.get("shipments", "").split(",")
+        access_type = "batch_labels" if doc == "label" else "batch_invoices"
+
+        error = validate_resource_token(request, "document", resource_ids, access_type)
+        if error:
+            return error
+
+        query_params = request.GET.dict()
+        self.attachment = "download" in query_params
+        self.format = (format or "").lower()
+        self.name = f"{doc}s - {timezone.now()}.{self.format}"
+
+        _queryset = Shipment.objects.filter(id__in=resource_ids)
+        if doc == "label":
+            _queryset = _queryset.filter(
+                label__isnull=False,
+                label_type__contains=self.format.upper(),
+            )
+        elif doc == "invoice":
+            _queryset = _queryset.filter(invoice__isnull=False)
+
+        self.documents = _queryset.values_list(doc, "label_type")
+
+        response = super().get(request, doc, self.format, **kwargs)
+        response["X-Frame-Options"] = "ALLOWALL"
+        return response
+
+    def get_file(self):
+        content = base64.b64decode(
+            lib.bundle_base64([doc for doc, _ in self.documents], self.format.upper())
+        )
+        buffer = io.BytesIO()
+        buffer.write(content)
+        return ContentFile(buffer.getvalue(), name=self.name)
+
+
+class OrderDocsPrinter(VirtualDownloadView):
+    @openapi.extend_schema(exclude=True)
+    def get(self, request, doc: str = "label", format: str = "pdf", **kwargs):
+        """Retrieve batch order labels or invoices."""
+        from karrio.server.orders.models import Order
+
+        if doc not in ["label", "invoice"]:
+            return JsonResponse(
+                dict(error=f"Invalid document type: {doc}"),
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        resource_ids = request.GET.get("orders", "").split(",")
+        access_type = "batch_labels" if doc == "label" else "batch_invoices"
+
+        error = validate_resource_token(request, "order", resource_ids, access_type)
+        if error:
+            return error
+
+        query_params = request.GET.dict()
+        self.attachment = "download" in query_params
+        self.format = (format or "").lower()
+        self.name = f"{doc}s - {timezone.now()}.{self.format}"
+
+        _queryset = Order.objects.filter(
+            id__in=resource_ids, shipments__id__isnull=False
+        ).distinct()
+
+        if doc == "label":
+            _queryset = _queryset.filter(
+                shipments__label__isnull=False,
+                shipments__label_type__contains=self.format.upper(),
+            )
+        elif doc == "invoice":
+            _queryset = _queryset.filter(shipments__invoice__isnull=False)
+
+        self.documents = list(
+            set(_queryset.values_list(f"shipments__{doc}", "shipments__label_type"))
+        )
+
+        response = super().get(request, doc, self.format, **kwargs)
+        response["X-Frame-Options"] = "ALLOWALL"
+        return response
+
+    def get_file(self):
+        content = base64.b64decode(
+            lib.bundle_base64([doc for doc, _ in self.documents], self.format.upper())
+        )
+        buffer = io.BytesIO()
+        buffer.write(content)
+        return ContentFile(buffer.getvalue(), name=self.name)
+
+
+class ManifestDocsPrinter(VirtualDownloadView):
+    @openapi.extend_schema(exclude=True)
+    def get(self, request, doc: str = "manifest", format: str = "pdf", **kwargs):
+        """Retrieve batch manifests."""
+        from karrio.server.manager.models import Manifest
+
+        if doc not in ["manifest"]:
+            return JsonResponse(
+                dict(error=f"Invalid document type: {doc}"),
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        resource_ids = request.GET.get("manifests", "").split(",")
+
+        error = validate_resource_token(request, "document", resource_ids, "batch_manifests")
+        if error:
+            return error
+
+        query_params = request.GET.dict()
+        self.attachment = "download" in query_params
+        self.format = (format or "").lower()
+        self.name = f"{doc}s - {timezone.now()}.{self.format}"
+
+        queryset = Manifest.objects.filter(id__in=resource_ids, manifest__isnull=False)
+        self.documents = queryset.values_list(doc, "reference")
+
+        response = super().get(request, doc, self.format, **kwargs)
+        response["X-Frame-Options"] = "ALLOWALL"
+        return response
+
+    def get_file(self):
+        content = base64.b64decode(
+            lib.bundle_base64([doc for doc, _ in self.documents], self.format.upper())
+        )
+        buffer = io.BytesIO()
+        buffer.write(content)
+        return ContentFile(buffer.getvalue(), name=self.name)
+
+
+urlpatterns = [
+    re_path(
+        r"^documents/templates/(?P<pk>\w+).(?P<slug>\w+)",
+        TemplateDocsPrinter.as_view(),
+        name="templates-documents-print",
+    ),
+    re_path(
+        r"^documents/shipments/(?P<doc>[a-z0-9]+).(?P<format>[a-zA-Z0-9]+)",
+        ShipmentDocsPrinter.as_view(),
+        name="shipments-documents-print",
+    ),
+    re_path(
+        r"^documents/orders/(?P<doc>[a-z0-9]+).(?P<format>[a-zA-Z0-9]+)",
+        OrderDocsPrinter.as_view(),
+        name="orders-documents-print",
+    ),
+    re_path(
+        r"^documents/manifests/(?P<doc>[a-z0-9]+).(?P<format>[a-zA-Z0-9]+)",
+        ManifestDocsPrinter.as_view(),
+        name="manifests-documents-print",
+    ),
+]

karrio/server/documents/views/templates.py

@@ -0,0 +1,255 @@
+import base64
+import django.urls as urls
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+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.documents.models as models
+import karrio.server.documents.generator as generator
+import karrio.server.documents.serializers as serializers
+from karrio.server.core.logging import logger
+
+ENDPOINT_ID = "&&&&$$"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+DocumentTemplates = serializers.PaginatedResult(
+    "DocumentTemplateList", serializers.DocumentTemplate
+)
+
+
+class DocumentTemplateList(api.GenericAPIView):
+    queryset = models.DocumentTemplate.objects
+    pagination_class = type(
+        "CustomPagination",
+        (pagination.LimitOffsetPagination,),
+        dict(default_limit=20),
+    )
+    serializer_class = DocumentTemplates
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}list",
+        extensions={"x-operationId": "listDocumentTemplates"},
+        summary="List all templates",
+        responses={
+            200: DocumentTemplates(),
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def get(self, request: Request):
+        """
+        Retrieve all templates.
+        """
+        templates = models.DocumentTemplate.access_by(request)
+        response = self.paginate_queryset(
+            serializers.DocumentTemplate(templates, many=True).data
+        )
+        return self.get_paginated_response(response)
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}create",
+        extensions={"x-operationId": "createDocumentTemplate"},
+        summary="Create a template",
+        request=serializers.DocumentTemplateData(),
+        responses={
+            201: serializers.DocumentTemplate(),
+            400: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def post(self, request: Request):
+        """
+        Create a new template.
+        """
+        template = (
+            serializers.DocumentTemplateModelSerializer.map(
+                data=request.data, context=request
+            )
+            .save()
+            .instance
+        )
+
+        return Response(
+            serializers.DocumentTemplate(template).data,
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class DocumentTemplateDetail(api.APIView):
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}retrieve",
+        extensions={"x-operationId": "retrieveDocumentTemplate"},
+        summary="Retrieve a template",
+        responses={
+            200: serializers.DocumentTemplate(),
+            400: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def get(self, request: Request, pk: str):
+        """
+        Retrieve a template.
+        """
+        template = models.DocumentTemplate.access_by(request).get(pk=pk)
+        return Response(serializers.DocumentTemplate(template).data)
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}update",
+        extensions={"x-operationId": "updateDocumentTemplate"},
+        summary="Update a template",
+        request=serializers.DocumentTemplateData(),
+        responses={
+            200: serializers.DocumentTemplate(),
+            400: serializers.ErrorResponse(),
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def patch(self, request: Request, pk: str):
+        """
+        update a template.
+        """
+        template = models.DocumentTemplate.access_by(request).get(pk=pk)
+
+        serializers.DocumentTemplateModelSerializer.map(
+            template,
+            data=request.data,
+        ).save()
+
+        return Response(serializers.DocumentTemplate(template).data)
+
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}discard",
+        extensions={"x-operationId": "discardDocumentTemplate"},
+        summary="Delete a template",
+        responses={
+            200: serializers.DocumentTemplate(),
+            404: serializers.ErrorResponse(),
+            409: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def delete(self, request: Request, pk: str):
+        """
+        Delete a template.
+        """
+        template = models.DocumentTemplate.access_by(request).get(pk=pk)
+
+        template.delete(keep_parents=True)
+
+        return Response(serializers.DocumentTemplate(template).data)
+
+
+class DocumentGenerator(api.APIView):
+    @openapi.extend_schema(
+        tags=["Documents"],
+        operation_id=f"{ENDPOINT_ID}generateDocument",
+        summary="Generate a document",
+        request=serializers.DocumentData(),
+        responses={
+            201: serializers.GeneratedDocument(),
+            400: serializers.ErrorResponse(),
+            404: serializers.ErrorResponse(),
+            500: serializers.ErrorResponse(),
+        },
+    )
+    def post(self, request: Request):
+        """Generate any document.
+        This API is designed to be used to generate GS1 labels,
+        invoices and any document that requires external data.
+        """
+        try:
+            data = serializers.DocumentData.map(data=request.data).data
+
+            if data.get("template") is None and data.get("template_id") is None:
+                return Response(
+                    {"errors": [{"message": "template or template_id is required"}]},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+
+            document_template = lib.identity(
+                None
+                if data.get("template_id") is None
+                else models.DocumentTemplate.objects.get(pk=data.get("template_id"))
+            )
+
+            try:
+                doc_file = generator.Documents.generate(
+                    getattr(document_template, "template", data.get("template")),
+                    related_object=getattr(document_template, "related_object", None),
+                    metadata=getattr(document_template, "metadata", {}),
+                    data=data.get("data", {}),
+                    options=data.get("options", {}),
+                    doc_name=data.get("doc_name"),
+                    doc_format=data.get("doc_format"),
+                )
+
+                document = serializers.GeneratedDocument.map(
+                    data={
+                        **data,
+                        "doc_file": base64.b64encode(doc_file.getvalue()).decode("utf-8"),
+                    }
+                )
+
+                return Response(document.data, status=status.HTTP_201_CREATED)
+
+            except generator.TemplateRenderingError as e:
+                error_message = e.message
+                if e.line_number:
+                    error_message += f" (line {e.line_number})"
+
+                return Response(
+                    {"errors": [{"message": error_message}]},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            except models.DocumentTemplate.DoesNotExist:
+                return Response(
+                    {"errors": [{"message": f"Document template with id '{data.get('template_id')}' not found"}]},
+                    status=status.HTTP_404_NOT_FOUND,
+                )
+            except Exception as e:
+                logger.exception("Document generation failed", template_id=data.get('template_id'), error=str(e))
+                return Response(
+                    {"errors": [{"message": f"Document generation failed: {str(e)}"}]},
+                    status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                )
+
+        except serializers.ValidationError as e:
+            logger.error("Document validation error", error=str(e))
+            return Response(
+                {"errors": [{"message": "Invalid input data"}]},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        except Exception as e:
+            logger.exception("Unexpected error in document generator", error=str(e))
+            return Response(
+                {"errors": [{"message": "Internal server error"}]},
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            )
+
+
+urlpatterns = [
+    urls.path(
+        "documents/templates",
+        DocumentTemplateList.as_view(),
+        name="document-template-list",
+    ),
+    urls.path(
+        "documents/templates/<str:pk>",
+        DocumentTemplateDetail.as_view(),
+        name="document-template-details",
+    ),
+    urls.path(
+        "documents/generate",
+        DocumentGenerator.as_view(),
+        name="document-generator",
+    ),
+]

karrio/server/graph/schemas/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore

karrio/server/graph/schemas/documents/__init__.py

@@ -0,0 +1,46 @@
+import strawberry
+from strawberry.types import Info
+
+import karrio.server.graph.utils as utils
+import karrio.server.graph.schemas.base as base
+import karrio.server.graph.schemas.documents.mutations as mutations
+import karrio.server.graph.schemas.documents.inputs as inputs
+import karrio.server.graph.schemas.documents.types as types
+import karrio.server.documents.models as models
+
+extra_types: list = []
+
+
+@strawberry.type
+class Query:
+    document_template: types.DocumentTemplateType = strawberry.field(
+        resolver=types.DocumentTemplateType.resolve
+    )
+    document_templates: utils.Connection[types.DocumentTemplateType] = strawberry.field(
+        resolver=types.DocumentTemplateType.resolve_list
+    )
+
+
+@strawberry.type
+class Mutation:
+    @strawberry.mutation
+    def create_document_template(
+        self, info: Info, input: inputs.CreateDocumentTemplateMutationInput
+    ) -> mutations.CreateDocumentTemplateMutation:
+        return mutations.CreateDocumentTemplateMutation.mutate(info, **input.to_dict())
+
+    @strawberry.mutation
+    def update_document_template(
+        self, info: Info, input: inputs.UpdateDocumentTemplateMutationInput
+    ) -> mutations.UpdateDocumentTemplateMutation:
+        return mutations.UpdateDocumentTemplateMutation.mutate(info, **input.to_dict())
+
+    @strawberry.mutation
+    def delete_document_template(
+        self, info: Info, input: base.inputs.DeleteMutationInput
+    ) -> base.mutations.DeleteMutation:
+        return base.mutations.DeleteMutation.mutate(
+            info,
+            model=models.DocumentTemplate,
+            **input.to_dict()
+        )

karrio/server/graph/schemas/documents/inputs.py

@@ -0,0 +1,41 @@
+import typing
+import strawberry
+
+import karrio.server.graph.utils as utils
+import karrio.server.documents.serializers as serializers
+
+TemplateRelatedObjectEnum: typing.Any = strawberry.enum(
+    serializers.TemplateRelatedObject
+)
+
+
+@strawberry.input
+class CreateDocumentTemplateMutationInput(utils.BaseInput):
+    slug: str
+    name: str
+    template: str
+    active: typing.Optional[bool] = True
+    description: typing.Optional[str] = strawberry.UNSET
+    metadata: typing.Optional[utils.JSON] = strawberry.UNSET
+    related_object: typing.Optional[TemplateRelatedObjectEnum] = strawberry.UNSET
+    options: typing.Optional[utils.JSON] = strawberry.UNSET
+
+
+@strawberry.input
+class UpdateDocumentTemplateMutationInput(utils.BaseInput):
+    id: str
+    slug: typing.Optional[str] = strawberry.UNSET
+    name: typing.Optional[str] = strawberry.UNSET
+    template: typing.Optional[str] = strawberry.UNSET
+    active: typing.Optional[bool] = strawberry.UNSET
+    description: typing.Optional[str] = strawberry.UNSET
+    metadata: typing.Optional[utils.JSON] = strawberry.UNSET
+    related_object: typing.Optional[TemplateRelatedObjectEnum] = strawberry.UNSET
+    options: typing.Optional[utils.JSON] = strawberry.UNSET
+
+
+@strawberry.input
+class DocumentTemplateFilter(utils.Paginated):
+    name: typing.Optional[str] = strawberry.UNSET
+    active: typing.Optional[bool] = strawberry.UNSET
+    related_object: typing.Optional[TemplateRelatedObjectEnum] = strawberry.UNSET

karrio/server/graph/schemas/documents/mutations.py

@@ -0,0 +1,51 @@
+import typing
+import strawberry
+from strawberry.types import Info
+
+import karrio.server.graph.utils as utils
+import karrio.server.graph.schemas.documents.types as types
+import karrio.server.graph.schemas.documents.inputs as inputs
+import karrio.server.documents.serializers as serializers
+import karrio.server.documents.models as models
+
+
+@strawberry.type
+class CreateDocumentTemplateMutation(utils.BaseMutation):
+    template: typing.Optional[types.DocumentTemplateType] = None
+
+    @staticmethod
+    @utils.authentication_required
+    @utils.authorization_required(["DOCUMENTS_MANAGEMENT", "manage_data"])
+    def mutate(
+        info: Info, **input: inputs.CreateDocumentTemplateMutationInput
+    ) -> "CreateDocumentTemplateMutation":
+        serializer = serializers.DocumentTemplateModelSerializer(
+            data=input,
+            context=info.context.request,
+        )
+        serializer.is_valid(raise_exception=True)
+
+        return CreateDocumentTemplateMutation(template=serializer.save())  # type:ignore
+
+
+@strawberry.type
+class UpdateDocumentTemplateMutation(utils.BaseMutation):
+    template: typing.Optional[types.DocumentTemplateType] = None
+
+    @staticmethod
+    @utils.authentication_required
+    @utils.authorization_required(["DOCUMENTS_MANAGEMENT", "manage_data"])
+    def mutate(
+        info: Info, **input: inputs.UpdateDocumentTemplateMutationInput
+    ) -> "UpdateDocumentTemplateMutation":
+        instance = models.DocumentTemplate.access_by(info.context.request).get(id=input["id"])
+
+        serializer = serializers.DocumentTemplateModelSerializer(
+            instance,
+            data=input,
+            partial=True,
+            context=info.context.request,
+        )
+        serializer.is_valid(raise_exception=True)
+
+        return UpdateDocumentTemplateMutation(template=serializer.save())  # type:ignore

karrio/server/graph/schemas/documents/types.py

@@ -0,0 +1,45 @@
+import typing
+import datetime
+import strawberry
+
+import karrio.lib as lib
+import karrio.server.graph.utils as utils
+import karrio.server.graph.schemas.base.types as base
+import karrio.server.graph.schemas.documents.inputs as inputs
+import karrio.server.documents.models as models
+import karrio.server.documents.filters as filters
+
+
+@strawberry.type
+class DocumentTemplateType:
+    object_type: str
+    preview_url: typing.Optional[str]
+    id: str
+    name: str
+    slug: str
+    template: str
+    active: bool
+    description: typing.Optional[str]
+    related_object: typing.Optional[inputs.TemplateRelatedObjectEnum]
+    metadata: typing.Optional[utils.JSON]
+    options: typing.Optional[utils.JSON]
+    created_at: typing.Optional[datetime.datetime]
+    updated_at: typing.Optional[datetime.datetime]
+    created_by: typing.Optional[base.UserType]
+
+    @staticmethod
+    @utils.authentication_required
+    def resolve(info, id: str) -> typing.Optional["DocumentTemplateType"]:
+        return models.DocumentTemplate.access_by(info.context.request).filter(id=id).first()
+
+    @staticmethod
+    @utils.authentication_required
+    def resolve_list(
+        info,
+        filter: typing.Optional[inputs.DocumentTemplateFilter] = strawberry.UNSET,
+    ) -> utils.Connection["DocumentTemplateType"]:
+        _filter = filter if filter is not strawberry.UNSET else inputs.DocumentTemplateFilter()
+        queryset = filters.DocumentTemplateFilter(
+            _filter.to_dict(), models.DocumentTemplate.access_by(info.context.request)
+        ).qs
+        return utils.paginated_connection(queryset, **_filter.pagination())

karrio_server_documents-2025.5.2.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: karrio_server_documents
+Version: 2025.5.2
+Summary: Multi-carrier shipping API apps module
+Author-email: karrio <hello@karrio.io>
+License-Expression: LGPL-3.0
+Project-URL: Homepage, https://github.com/karrioapi/karrio
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyzint
+Requires-Dist: weasyprint
+Requires-Dist: karrio_server_core
+Requires-Dist: karrio_server_graph
+Requires-Dist: karrio_server_manager
+
+# karrio-server
+
+Karrio server documents module.