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

karrio/server/providers/models/service.py

@@ -0,0 +1,62 @@
+import functools
+import django.db.models as models
+import django.core.validators as validators
+
+import karrio.server.core.models as core
+import karrio.server.core.datatypes as datatypes
+
+
+@core.register_model
+class ServiceLevel(core.OwnedEntity):
+    class Meta:
+        db_table = "service-level"
+        verbose_name = "Service Level"
+        verbose_name_plural = "Service Levels"
+        ordering = ["-created_at"]
+
+    id = models.CharField(
+        max_length=50,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="svc_"),
+        editable=False,
+    )
+    service_name = models.CharField(max_length=50)
+    service_code = models.CharField(
+        max_length=50, validators=[validators.RegexValidator(r"^[a-z0-9_]+$")]
+    )
+    carrier_service_code = models.CharField(max_length=50, null=True, blank=True)
+    description = models.CharField(max_length=250, null=True, blank=True)
+    active = models.BooleanField(null=True, default=True)
+
+    currency = models.CharField(
+        max_length=4, choices=datatypes.CURRENCIES, null=True, blank=True
+    )
+
+    transit_days = models.IntegerField(blank=True, null=True)
+    transit_time = models.FloatField(blank=True, null=True)
+
+    max_width = models.FloatField(blank=True, null=True)
+    max_height = models.FloatField(blank=True, null=True)
+    max_length = models.FloatField(blank=True, null=True)
+    dimension_unit = models.CharField(
+        max_length=2, choices=datatypes.DIMENSION_UNITS, null=True, blank=True
+    )
+
+    min_weight = models.FloatField(blank=True, null=True)
+    max_weight = models.FloatField(blank=True, null=True)
+    weight_unit = models.CharField(
+        max_length=2, choices=datatypes.WEIGHT_UNITS, null=True, blank=True
+    )
+
+    domicile = models.BooleanField(null=True)
+    international = models.BooleanField(null=True)
+
+    zones = models.JSONField(blank=True, null=True, default=core.field_default([]))
+    metadata = models.JSONField(blank=True, null=True, default=core.field_default({}))
+
+    def __str__(self):
+        return f"{self.id} | {self.service_name}"
+
+    @property
+    def object_type(self):
+        return "service_level"

karrio/server/providers/models/sheet.py

@@ -0,0 +1,60 @@
+import functools
+import django.db.models as models
+import django.utils.translation as translation
+
+import django.conf as conf
+import karrio.server.core.models as core
+
+_ = translation.gettext_lazy
+
+
+@core.register_model
+class RateSheet(core.OwnedEntity):
+    class Meta:
+        db_table = "rate-sheet"
+        verbose_name = "Rate Sheet"
+        verbose_name_plural = "Rate Sheets"
+        ordering = ["-created_at"]
+
+    id = models.CharField(
+        max_length=50,
+        editable=False,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="rsht_"),
+    )
+    name = models.CharField(_("name"), max_length=50, db_index=True)
+    slug = models.CharField(_("slug"), max_length=50, db_index=True)
+    carrier_name = models.CharField(max_length=50, db_index=True)
+    is_system = models.BooleanField(default=False, db_index=True)
+    services = models.ManyToManyField(
+        "ServiceLevel", blank=True, related_name="service_sheet"
+    )
+    metadata = models.JSONField(
+        blank=True,
+        null=True,
+        default=core.field_default({}),
+    )
+
+    created_by = models.ForeignKey(
+        conf.settings.AUTH_USER_MODEL,
+        blank=True,
+        null=True,
+        on_delete=models.CASCADE,
+        editable=False,
+    )
+
+    def delete(self, *args, **kwargs):
+        self.services.all().delete()
+        return super().delete(*args, **kwargs)
+
+    @property
+    def object_type(self):
+        return "rate-sheet"
+
+    @property
+    def carriers(self):
+        import karrio.server.providers.models as providers
+
+        return providers.Carrier.objects.filter(
+            carrier_code=self.carrier_name, rate_sheet__id=self.id
+        )

karrio/server/providers/models/template.py

@@ -0,0 +1,39 @@
+import functools
+import django.db.models as models
+import django.core.validators as validators
+import karrio.server.core.models as core
+
+
+LABEL_TEMPLATE_TYPES = [
+    ("SVG", "SVG"),
+    ("ZPL", "ZPL"),
+]
+
+
+@core.register_model
+class LabelTemplate(core.OwnedEntity):
+    class Meta:
+        db_table = "label-template"
+        verbose_name = "Label Template"
+        verbose_name_plural = "Label Templates"
+        ordering = ["-created_at"]
+
+    id = models.CharField(
+        max_length=50,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="tpl_"),
+        editable=False,
+    )
+    slug = models.SlugField(
+        max_length=30,
+        validators=[validators.RegexValidator(r"^[a-z0-9_]+$")],
+    )
+    template = models.TextField()
+    template_type = models.CharField(max_length=3, choices=LABEL_TEMPLATE_TYPES)
+    width = models.IntegerField(null=True, blank=True)
+    height = models.IntegerField(null=True, blank=True)
+    shipment_sample = models.JSONField(blank=True, null=True, default=dict)
+
+    @property
+    def object_type(self):
+        return "label_template"

karrio/server/providers/models/utils.py

@@ -0,0 +1,58 @@
+import django.db.models as models
+import django.core.cache as caching
+
+import karrio.lib as lib
+
+
+def has_rate_sheet(carrier_name: str):
+    def decorator(model: models.Model):
+        # Add a rate sheet relation to the model
+        model.add_to_class(
+            "rate_sheet",
+            models.ForeignKey(
+                "RateSheet",
+                null=True,
+                blank=True,
+                on_delete=models.SET_NULL,
+            ),
+        )
+
+        # Add a service list property to the model
+        setattr(
+            model,
+            "service_list",
+            property(
+                lambda self: (
+                    self.services
+                    if self.rate_sheet is None and hasattr(self, "services")
+                    else self.rate_sheet.services.all()
+                )
+            ),
+        )
+
+        # Add a default services property to the model
+        # skip if it already exists (overridden)
+        if not hasattr(model, "default_services"):
+            setattr(
+                model,
+                "default_services",
+                property(
+                    lambda self: lib.to_dict(
+                        getattr(
+                            getattr(
+                                __import__(
+                                    f"karrio.mappers.{carrier_name}", fromlist=["units"]
+                                ),
+                                "units",
+                                None,
+                            ),
+                            "DEFAULT_SERVICES",
+                            [],
+                        )
+                    )
+                ),
+            )
+
+        return model
+
+    return decorator

karrio/server/providers/router.py

@@ -0,0 +1,3 @@
+from rest_framework.routers import DefaultRouter
+
+router = DefaultRouter(trailing_slash=False)

karrio/server/providers/serializers/__init__.py

@@ -0,0 +1,3 @@
+from karrio.server.serializers import *
+from karrio.server.core.serializers import *
+from karrio.server.providers.serializers.base import *

karrio/server/providers/serializers/base.py

@@ -0,0 +1,277 @@
+import typing
+import django.db.transaction as transaction
+
+import karrio.lib as lib
+import karrio.references as references
+import karrio.server.openapi as openapi
+import karrio.server.core.utils as utils
+import karrio.server.serializers as serializers
+import karrio.server.core.dataunits as dataunits
+import karrio.server.providers.models as providers
+from karrio.server.core.serializers import CARRIERS
+
+
+def generate_carrier_serializers() -> typing.Dict[str, serializers.Serializer]:
+
+    def _create_serializer(carrier_name: str) -> serializers.Serializer:
+        fields = dataunits.REFERENCE_MODELS["connection_fields"][carrier_name]
+        return type(
+            carrier_name,
+            (serializers.Serializer,),
+            {
+                key: serializers.field_to_serializer(field)
+                for key, field in fields.items()
+            },
+        )
+
+    return {
+        carrier_name: _create_serializer(carrier_name)
+        for carrier_name in dataunits.REFERENCE_MODELS["carriers"].keys()
+    }
+
+
+CONNECTION_SERIALIZERS = generate_carrier_serializers()
+
+
+@openapi.extend_schema_field(
+    openapi.PolymorphicProxySerializer(
+        component_name="ConnectionCredentialsField",
+        serializers=CONNECTION_SERIALIZERS.values(),
+        resource_type_field_name=None,
+    )
+)
+class ConnectionCredentialsField(serializers.DictField):
+    pass
+
+
+@serializers.owned_model_serializer
+class CarrierConfigModelSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = providers.CarrierConfig
+        exclude = ["created_at", "updated_at", "created_by"]
+        extra_kwargs = {field: {"read_only": True} for field in ["id"]}
+
+
+class CarrierConnectionData(serializers.Serializer):
+
+    carrier_name = serializers.ChoiceField(
+        choices=CARRIERS,
+        required=True,
+        help_text="A carrier connection type.",
+    )
+    carrier_id = serializers.CharField(
+        required=True,
+        help_text="A carrier connection friendly name.",
+    )
+    credentials = ConnectionCredentialsField(
+        required=True,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    active = serializers.BooleanField(
+        required=False,
+        default=True,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+
+
+class CarrierConnectionUpdateData(serializers.Serializer):
+    carrier_id = serializers.CharField(
+        required=False, help_text="A carrier connection friendly name."
+    )
+    credentials = serializers.PlainDictField(
+        required=False,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    active = serializers.BooleanField(
+        required=False,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+
+
+class CarrierConnection(serializers.Serializer):
+    id = serializers.CharField(
+        required=True,
+        help_text="A unique carrier connection identifier",
+    )
+    object_type = serializers.CharField(
+        default="carrier-connection",
+        help_text="Specifies the object type",
+    )
+    carrier_name = serializers.ChoiceField(
+        choices=CARRIERS,
+        required=True,
+        help_text="A carrier connection type.",
+    )
+    display_name = serializers.CharField(
+        required=False,
+        help_text="The carrier connection type verbose name.",
+    )
+    carrier_id = serializers.CharField(
+        required=True,
+        help_text="A carrier connection friendly name.",
+    )
+    credentials = ConnectionCredentialsField(
+        required=False,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    is_system = serializers.BooleanField(
+        required=True,
+        help_text="The carrier connection is provided by the system admin.",
+    )
+    active = serializers.BooleanField(
+        required=True,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+    test_mode = serializers.BooleanField(
+        required=True,
+        help_text="The test flag indicates whether to use a carrier configured for test.",
+    )
+
+
+@serializers.owned_model_serializer
+class CarrierConnectionModelSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = providers.Carrier
+        exclude = ["created_at", "updated_at", "created_by"]
+
+    carrier_name = serializers.ChoiceField(
+        required=True, choices=CARRIERS, help_text="Indicates a carrier (type)"
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        allow_null=True,
+        help_text="Carrier connection custom config.",
+    )
+
+    @transaction.atomic
+    @utils.error_wrapper
+    def create(
+        self,
+        validated_data: dict,
+        context: serializers.Context,
+        **kwargs,
+    ) -> providers.Carrier:
+        config = validated_data.pop("config")
+        carrier_name = validated_data.pop("carrier_name")
+        default_capabilities = references.get_carrier_capabilities(carrier_name)
+        capabilities = lib.identity(
+            validated_data.get("capabilities")
+            if any(validated_data.get("capabilities") or [])
+            else default_capabilities
+        )
+
+        validated_data.update(test_mode=context.test_mode)
+        validated_data.update(carrier_code=carrier_name)
+        validated_data.update(
+            capabilities=[_ for _ in capabilities if _ in default_capabilities]
+        )
+        validated_data.update(
+            credentials=CONNECTION_SERIALIZERS[carrier_name]
+            .map(data=validated_data["credentials"])
+            .data
+        )
+
+        instance = super().create(validated_data, context=context, **kwargs)
+
+        if config is not None:
+            CarrierConfigModelSerializer.map(
+                context=context,
+                data={"carrier": instance.pk, "config": config},
+            ).save()
+
+        return providers.Carrier.objects.get(pk=instance.pk)
+
+    @transaction.atomic
+    @utils.error_wrapper
+    def update(
+        self,
+        instance: providers.Carrier,
+        validated_data: dict,
+        **kwargs,
+    ) -> providers.Carrier:
+        if any(validated_data.get("capabilities") or []):
+            default_capabilities = references.get_carrier_capabilities(instance.ext)
+            capabilities = validated_data.get("capabilities")
+            instance.capabilities = [
+                _ for _ in capabilities if _ in default_capabilities
+            ]
+
+        if "credentials" in validated_data:
+            data = serializers.process_dictionaries_mutations(
+                ["credentials"],
+                validated_data,
+                instance,
+            )
+            validated_data.update(
+                credentials=CONNECTION_SERIALIZERS[instance.ext]
+                .map(data=data["credentials"])
+                .data
+            )
+
+        if "config" in validated_data:
+            data = serializers.process_dictionaries_mutations(
+                ["config"],
+                dict(config=validated_data.pop("config")),
+                instance,
+            )
+            lib.identity(
+                CarrierConfigModelSerializer.map(
+                    instance=instance.carrier_config,
+                    context=kwargs.get("context"),
+                    data={"carrier": instance.pk, **data},
+                )
+                .save()
+                .instance
+            )
+
+        return super().update(instance, validated_data, **kwargs)

karrio/server/providers/signals.py

@@ -0,0 +1,27 @@
+import logging
+from django.db.models import signals
+
+import karrio.references as ref
+import karrio.server.core.utils as utils
+import karrio.server.providers.models as models
+
+logger = logging.getLogger(__name__)
+
+
+def register_signals():
+    signals.post_save.connect(carrier_changed, sender=models.Carrier)
+
+    logger.info("karrio.providers signals registered...")
+
+
+@utils.disable_for_loaddata
+def carrier_changed(
+    sender, instance, created, raw, using, update_fields, *args, **kwargs
+):
+    """Setup default capabilities when carrier are created."""
+    if not created:
+        return
+
+    if len(instance.capabilities or []) == 0:
+        instance.capabilities = ref.get_carrier_capabilities(instance.carrier_code)
+        instance.save()

karrio/server/providers/tests.py

@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# TODO: Write carriers API tests

karrio/server/providers/urls.py

@@ -0,0 +1,11 @@
+"""
+karrio server providers module urls
+"""
+
+from django.urls import include, path
+
+app_name = "karrio.server.providers"
+urlpatterns = [
+    path("v1/", include("karrio.server.providers.views.carriers")),
+    path("v1/", include("karrio.server.providers.views.connections")),
+]