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

karrio/server/providers/migrations/0086_rename_dhl_parcel_de_customer_number_to_billing_number.py

@@ -0,0 +1,71 @@
+# Generated by Django migration to rename customer_number to billing_number
+# for DHL Parcel DE connections. This keeps existing configuration values
+# when the field was renamed in the settings schema.
+
+from django.db import migrations
+
+
+def rename_customer_number_to_billing_number(apps, schema_editor):
+    """
+    Find all dhl_parcel_de carrier connections that have customer_number
+    and rename it to billing_number to preserve the configuration value.
+    """
+    Carrier = apps.get_model("providers", "Carrier")
+    db_alias = schema_editor.connection.alias
+
+    # Find all dhl_parcel_de carriers
+    dhl_parcel_de_carriers = Carrier.objects.using(db_alias).filter(
+        carrier_code="dhl_parcel_de"
+    )
+
+    for carrier in dhl_parcel_de_carriers:
+        credentials = carrier.credentials or {}
+
+        # Check if customer_number exists and billing_number doesn't
+        if credentials.get("customer_number") and not credentials.get("billing_number"):
+            # Copy customer_number value to billing_number
+            credentials["billing_number"] = credentials["customer_number"]
+            # Remove old customer_number field
+            del credentials["customer_number"]
+
+            carrier.credentials = credentials
+            carrier.save(using=db_alias, update_fields=["credentials"])
+
+
+def rename_billing_number_to_customer_number(apps, schema_editor):
+    """
+    Reverse migration: rename billing_number back to customer_number.
+    """
+    Carrier = apps.get_model("providers", "Carrier")
+    db_alias = schema_editor.connection.alias
+
+    dhl_parcel_de_carriers = Carrier.objects.using(db_alias).filter(
+        carrier_code="dhl_parcel_de"
+    )
+
+    for carrier in dhl_parcel_de_carriers:
+        credentials = carrier.credentials or {}
+
+        # Check if billing_number exists and customer_number doesn't
+        if credentials.get("billing_number") and not credentials.get("customer_number"):
+            # Copy billing_number value back to customer_number
+            credentials["customer_number"] = credentials["billing_number"]
+            # Remove the billing_number field
+            del credentials["billing_number"]
+
+            carrier.credentials = credentials
+            carrier.save(using=db_alias, update_fields=["credentials"])
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("providers", "0085_populate_dhl_parcel_de_oauth_credentials"),
+    ]
+
+    operations = [
+        migrations.RunPython(
+            rename_customer_number_to_billing_number,
+            rename_billing_number_to_customer_number,
+        ),
+    ]

karrio/server/providers/models/__init__.py

@@ -0,0 +1,16 @@
+
+from karrio.server.providers.models.sheet import RateSheet
+from karrio.server.providers.models.config import CarrierConfig
+from karrio.server.providers.models.service import ServiceLevel
+from karrio.server.providers.models.template import LabelTemplate
+from karrio.server.providers.models.utils import has_rate_sheet
+from karrio.server.core.models.base import register_model
+from karrio.server.providers.models.carrier import (
+    Carrier,
+    COUNTRIES,
+    CURRENCIES,
+    WEIGHT_UNITS,
+    DIMENSION_UNITS,
+    CAPABILITIES_CHOICES,
+    create_carrier_proxy,
+)

karrio/server/providers/models/carrier.py

@@ -0,0 +1,387 @@
+import typing
+import functools
+import django.conf as conf
+import django.forms as forms
+import django.db.models as models
+from django.db.models import Q, OuterRef, Subquery, Case, When, IntegerField
+
+import karrio.lib as lib
+import karrio.sdk as karrio
+import karrio.core.units as units
+import django.core.cache as caching
+import karrio.api.gateway as gateway
+import karrio.server.core.models as core
+import karrio.server.core.fields as fields
+import karrio.server.core.datatypes as datatypes
+
+
+COUNTRIES = [(c.name, c.name) for c in units.Country]
+CURRENCIES = [(c.name, c.name) for c in units.Currency]
+WEIGHT_UNITS = [(c.name, c.name) for c in units.WeightUnit]
+DIMENSION_UNITS = [(c.name, c.name) for c in units.DimensionUnit]
+CAPABILITIES_CHOICES = [(c, c) for c in units.CarrierCapabilities.get_capabilities()]
+
+
+class CarrierQuerySet(models.QuerySet):
+    def resolve_config_for(self, context):
+        from karrio.server.providers.models.config import CarrierConfig
+
+        if context is None:
+            return self
+
+        user = getattr(context, "user", None)
+        org = getattr(context, "org", None)
+
+        if isinstance(context, dict):
+            user = user or context.get("user")
+            org = org or context.get("org")
+
+        # 1. Define what "My Config" looks like (User or Org specific)
+        my_config_filter = Q()
+        if org:
+            my_config_filter = Q(org=org)
+        elif user and getattr(user, "is_authenticated", False):
+            my_config_filter = Q(created_by=user)
+
+        # 2. Define what "System Default" looks like
+        system_default_filter = Q(created_by__is_staff=True)
+        if hasattr(CarrierConfig, "org"):
+            system_default_filter &= Q(org__isnull=True)
+
+        # 3. Build the Subquery - only use priority if we have a user/org filter
+        config_filter = (
+            my_config_filter | system_default_filter
+            if my_config_filter
+            else system_default_filter
+        )
+
+        config_query = CarrierConfig.objects.filter(carrier=OuterRef("pk")).filter(
+            config_filter
+        )
+
+        if my_config_filter:
+            # Prioritize user/org config over system default
+            config_query = config_query.annotate(
+                priority=Case(
+                    When(my_config_filter, then=0),
+                    default=1,
+                    output_field=IntegerField(),
+                )
+            ).order_by("priority")
+
+        # 4. Annotate the queryset
+        return self.annotate(
+            _computed_config=Subquery(config_query.values("config")[:1])
+        )
+
+
+class Manager(models.Manager):
+    def get_queryset(self):
+        return (
+            CarrierQuerySet(self.model, using=self._db)
+            .select_related(
+                "created_by",
+                "rate_sheet",
+                *(("link",) if conf.settings.MULTI_ORGANIZATIONS else tuple()),
+            )
+            .prefetch_related(
+                "active_users",
+                *(("org",) if conf.settings.MULTI_ORGANIZATIONS else tuple()),
+            )
+        )
+
+    def resolve_config_for(self, context):
+        return self.get_queryset().resolve_config_for(context)
+
+
+class CarrierManager(Manager):
+    def get_queryset(self):
+        return super().get_queryset().filter(is_system=False)
+
+
+class SystemCarrierManager(models.Manager):
+    def get_queryset(self):
+        return (
+            CarrierQuerySet(self.model, using=self._db)
+            .prefetch_related(
+                *(("active_orgs",) if conf.settings.MULTI_ORGANIZATIONS else tuple()),
+            )
+            .select_related(
+                "created_by",
+                *(("link",) if conf.settings.MULTI_ORGANIZATIONS else tuple()),
+            )
+            .filter(is_system=True)
+        )
+
+    def resolve_config_for(self, context):
+        return self.get_queryset().resolve_config_for(context)
+
+
+@core.register_model
+class Carrier(core.OwnedEntity):
+    class Meta:
+        ordering = ["test_mode", "-created_at"]
+
+    CONTEXT_RELATIONS = ["rate_sheet"]
+
+    objects = Manager()
+    user_carriers = CarrierManager()
+    system_carriers = SystemCarrierManager()
+
+    id = models.CharField(
+        max_length=50,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="car_"),
+        editable=False,
+    )
+    carrier_code = models.CharField(
+        max_length=100,
+        db_index=True,
+        default="generic",
+        help_text="eg. dhl_express, fedex, ups, usps, ...",
+    )
+    carrier_id = models.CharField(
+        max_length=150,
+        db_index=True,
+        help_text="eg. canadapost, dhl_express, fedex, purolator_courrier, ups...",
+    )
+    credentials = models.JSONField(
+        default=core.field_default({}),
+        help_text="Carrier connection credentials",
+    )
+    capabilities = fields.MultiChoiceField(
+        choices=datatypes.CAPABILITIES_CHOICES,
+        default=core.field_default([]),
+        help_text="Select the capabilities of the carrier that you want to enable",
+    )
+    metadata = models.JSONField(
+        blank=True,
+        null=True,
+        default=core.field_default({}),
+        help_text="User defined metadata",
+    )
+    active = models.BooleanField(
+        default=True,
+        db_index=True,
+        help_text="Disable/Hide carrier from clients",
+    )
+    is_system = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Determine that the carrier connection is available system wide.",
+    )
+    test_mode = models.BooleanField(
+        default=True,
+        db_column="test_mode",
+        help_text="Toggle carrier connection mode",
+    )
+
+    created_by = models.ForeignKey(
+        conf.settings.AUTH_USER_MODEL,
+        blank=True,
+        null=True,
+        on_delete=models.CASCADE,
+        editable=False,
+    )
+    active_users = models.ManyToManyField(
+        conf.settings.AUTH_USER_MODEL,
+        blank=True,
+        related_name="connection_users",
+    )
+    rate_sheet = models.ForeignKey(
+        "RateSheet",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+    )
+
+    @classmethod
+    def resolve_context_data(cls, queryset, context):
+        """Apply context-aware carrier config resolution."""
+        return queryset.resolve_config_for(context)
+
+    def __str__(self):
+        return self.carrier_id
+
+    @property
+    def object_type(self):
+        return "carrier-connection"
+
+    @property
+    def ext(self) -> str:
+        return (
+            "generic"
+            if "custom_carrier_name" in self.credentials
+            else lib.failsafe(lambda: self.carrier_code) or "generic"
+        )
+
+    @property
+    def carrier_name(self):
+        return (
+            "generic"
+            if "custom_carrier_name" in self.credentials
+            else lib.failsafe(lambda: self.carrier_code) or "generic"
+        )
+
+    @property
+    def display_name(self):
+        import karrio.references as references
+
+        return (
+            self.credentials.get("display_name")
+            or references.REFERENCES["carriers"].get(self.ext)
+            or "generic"
+        )
+
+    @property
+    def carrier_config(self):
+        return self.__class__.resolve_config(self)
+
+    @property
+    def config(self) -> dict:
+        if hasattr(self, "_computed_config"):
+            annotated_config = self._computed_config
+            if annotated_config is not None:
+                return annotated_config
+            # If the annotation didn't resolve (eg. context missing), fall back to DB lookup.
+        resolved_config = getattr(self.carrier_config, "config", None)
+        if resolved_config is not None:
+            return resolved_config
+        # Return empty dict if no config is found - do NOT fallback to credentials
+        return {}
+
+    @property
+    def services(self) -> typing.Optional[typing.List[dict]]:
+
+        if self.rate_sheet is None:
+            return None
+
+        return self.rate_sheet.services.all()
+
+    @property
+    def data(self) -> datatypes.CarrierSettings:
+        _computed_data: typing.Dict = dict(
+            id=self.id,
+            config=self.config,
+            test_mode=self.test_mode,
+            metadata=self.metadata,
+            carrier_id=self.carrier_id,
+            carrier_name=self.ext,
+            display_name=self.display_name,
+        )
+
+        if any(self.services or []):
+            _computed_data.update(
+                services=[forms.model_to_dict(s) for s in self.services]
+            )
+
+        # override the config with the system config
+        if self.is_system and self.carrier_config is None:
+            _config = self.__class__.resolve_config(self, is_system_config=True)
+            _computed_data.update(config=getattr(_config, "config", None))
+
+        return datatypes.CarrierSettings.create(
+            {
+                **self.credentials,
+                **_computed_data,
+            }
+        )
+
+    @property
+    def gateway(self) -> gateway.Gateway:
+        import karrio.server.core.middleware as middleware
+        import karrio.server.core.config as system_config
+
+        _context = middleware.SessionContext.get_current_request()
+        _tracer = getattr(_context, "tracer", lib.Tracer())
+        _cache = lib.Cache(caching.cache)
+        _config = lib.SystemConfig(system_config.config)
+
+        return karrio.gateway[self.ext].create(
+            self.data.to_dict(),
+            _tracer,
+            _cache,
+            _config,
+        )
+
+    @staticmethod
+    def resolve_config(
+        carrier, is_user_config: bool = False, is_system_config: bool = False
+    ):
+        import karrio.server.serializers as serializers
+        import karrio.server.core.middleware as middleware
+        from django.contrib.auth.models import AnonymousUser
+        from karrio.server.providers.models.config import CarrierConfig
+
+        if carrier.id is None:
+            return None
+
+        _ctx = serializers.get_object_context(carrier)
+        ctx = lib.identity(
+            _ctx
+            if (_ctx.user or _ctx.org)
+            else lib.failsafe(lambda: middleware.SessionContext.get_current_request())
+        )
+        has_ctx_user = lib.identity(
+            ctx and ((ctx.user and not isinstance(ctx.user, AnonymousUser)) or ctx.org)
+        )
+
+        queryset = lib.identity(
+            CarrierConfig.objects.filter(carrier=carrier)
+            if carrier.is_system
+            else CarrierConfig.access_by(ctx).filter(carrier=carrier)
+        )
+
+        if carrier.is_system:
+            _config = queryset.filter(
+                created_by__is_staff=True,
+                **({"org": None} if hasattr(carrier, "org") else {}),
+            ).first()
+
+            if has_ctx_user:
+                return queryset.filter(
+                    **(
+                        {"org": (None if is_system_config else ctx.org)}
+                        if hasattr(carrier, "org")
+                        else {"created_by": ctx.user}
+                    )
+                ).first() or (None if is_user_config else _config)
+
+            return _config
+
+        return queryset.first()
+
+
+def create_carrier_proxy(carrier_name: str, display_name):
+    class _Manager(Manager):
+        def get_queryset(self):
+            return super().get_queryset().filter(carrier_code=carrier_name)
+
+    class _CarrierManager(CarrierManager):
+        def get_queryset(self):
+            return super().get_queryset().filter(carrier_code=carrier_name)
+
+    class _SystemCarrierManager(SystemCarrierManager):
+        def get_queryset(self):
+            return super().get_queryset().filter(carrier_code=carrier_name)
+
+    return type(
+        f"{carrier_name}Connection",
+        (Carrier,),
+        {
+            "Meta": type(
+                "Meta",
+                (),
+                {
+                    "proxy": True,
+                    "__module__": __name__,
+                    "verbose_name": f"{display_name} Connection",
+                    "verbose_name_plural": f"{display_name} Connections",
+                },
+            ),
+            "__module__": __name__,
+            "objects": _Manager(),
+            "user_carriers": _CarrierManager(),
+            "system_carriers": _SystemCarrierManager(),
+        },
+    )

karrio/server/providers/models/config.py

@@ -0,0 +1,30 @@
+import functools
+import django.db.models as models
+import karrio.server.core.models as core
+
+
+@core.register_model
+class CarrierConfig(core.OwnedEntity):
+    class Meta:
+        db_table = "carrier-config"
+        verbose_name = "Carrier Config"
+        verbose_name_plural = "Carrier Configs"
+        ordering = ["-created_at"]
+
+    id = models.CharField(
+        max_length=50,
+        editable=False,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="cfg_"),
+    )
+    carrier = models.ForeignKey(
+        "Carrier",
+        null=False,
+        related_name="configs",
+        on_delete=models.CASCADE,
+    )
+    config = models.JSONField(
+        null=False,
+        blank=False,
+        default=core.field_default({}),
+    )

karrio/server/providers/models/service.py

@@ -0,0 +1,192 @@
+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"
+    
+    @property 
+    def computed_zones(self):
+        """
+        Computed property that returns zones in legacy format for backward compatibility.
+        If the service belongs to a rate sheet with optimized structure, reconstruct from there.
+        Otherwise, fall back to the service's own zones field.
+        """
+        # Check if this service belongs to a rate sheet with optimized structure
+        rate_sheet = getattr(self, '_rate_sheet_cache', None)
+        if not rate_sheet:
+            # Try to find rate sheet this service belongs to
+            try:
+                rate_sheet = self.service_sheet.first()
+                self._rate_sheet_cache = rate_sheet
+            except:
+                rate_sheet = None
+        
+        if rate_sheet and rate_sheet.zones and rate_sheet.service_rates:
+            # Use optimized structure
+            return rate_sheet.get_service_zones_legacy(self.id)
+        else:
+            # Fall back to legacy zones field
+            return self.zones or []
+    
+    def update_zone_cell(self, zone_id: str, field: str, value):
+        """Update a single field in a zone by ID or index with validation"""
+        # Define allowed fields with their validators
+        allowed_fields = {
+            'rate': float,
+            'min_weight': float,
+            'max_weight': float,
+            'transit_days': int,
+            'transit_time': float,
+            'label': str,
+            'radius': float,
+            'latitude': float,
+            'longitude': float,
+        }
+        
+        if field not in allowed_fields:
+            raise ValueError(f"Field '{field}' is not allowed for zone updates")
+        
+        # Validate and convert the value
+        try:
+            if value is not None and value != '':
+                value = allowed_fields[field](value)
+        except (ValueError, TypeError):
+            raise ValueError(f"Invalid value '{value}' for field '{field}' (expected {allowed_fields[field].__name__})")
+        
+        zones = self.zones or []
+        
+        # First try to find by zone ID
+        for zone in zones:
+            if zone.get('id') == zone_id:
+                zone[field] = value
+                self.save(update_fields=['zones'])
+                return zone
+        
+        # Fallback: try to find by index for zones without IDs
+        try:
+            zone_index = int(zone_id)
+            if 0 <= zone_index < len(zones):
+                zones[zone_index][field] = value
+                self.save(update_fields=['zones'])
+                return zones[zone_index]
+        except (ValueError, IndexError):
+            pass
+        
+        raise ValueError(f"Zone {zone_id} not found")
+    
+    def batch_update_cells(self, updates: list):
+        """
+        Batch update multiple zone cells with validation
+        updates format: [{'zone_id': str, 'field': str, 'value': any}, ...]
+        """
+        # Define allowed fields with their validators
+        allowed_fields = {
+            'rate': float,
+            'min_weight': float,
+            'max_weight': float,
+            'transit_days': int,
+            'transit_time': float,
+            'label': str,
+            'radius': float,
+            'latitude': float,
+            'longitude': float,
+        }
+        
+        zones = list(self.zones or [])
+        
+        for update in updates:
+            zone_id = update.get('zone_id')
+            field = update.get('field')
+            value = update.get('value')
+            
+            if field not in allowed_fields:
+                raise ValueError(f"Field '{field}' is not allowed for zone updates")
+            
+            # Validate and convert the value
+            try:
+                if value is not None and value != '':
+                    value = allowed_fields[field](value)
+            except (ValueError, TypeError):
+                raise ValueError(f"Invalid value '{value}' for field '{field}' (expected {allowed_fields[field].__name__})")
+            
+            # Find zone by ID first, then by index
+            zone_found = False
+            for zone in zones:
+                if zone.get('id') == zone_id:
+                    zone[field] = value
+                    zone_found = True
+                    break
+            
+            # Fallback to index if zone_id is numeric and zone not found by ID
+            if not zone_found:
+                try:
+                    zone_index = int(zone_id)
+                    if 0 <= zone_index < len(zones):
+                        zones[zone_index][field] = value
+                        zone_found = True
+                except (ValueError, IndexError):
+                    pass
+            
+            if not zone_found:
+                raise ValueError(f"Zone {zone_id} not found")
+
+        self.zones = zones
+        self.save(update_fields=['zones'])
+        return self.zones