karrio-server-pricing 2026.1.1__py3-none-any.whl → 2026.1.3__py3-none-any.whl

karrio/server/pricing/models.py

@@ -2,147 +2,213 @@ import typing
 import functools
 import django.db.models as models
 import django.core.validators as validators
+from django.contrib.contenttypes.fields import GenericRelation
 
 import karrio.lib as lib
 import karrio.core.models as karrio
 import karrio.server.core.models as core
-import karrio.server.core.fields as fields
 import karrio.server.core.datatypes as datatypes
 import karrio.server.providers.models as providers
-import karrio.server.pricing.serializers as serializers
 from karrio.server.core.logging import logger
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# MARKUP TYPE ENUM
+# ─────────────────────────────────────────────────────────────────────────────
+
+MARKUP_TYPE_CHOICES = [
+    ("AMOUNT", "AMOUNT"),
+    ("PERCENTAGE", "PERCENTAGE"),
+]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MARKUP MODEL (replaces Surcharge)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
 @core.register_model
-class Surcharge(core.ControlledAccessModel, core.Entity):
+class Markup(core.Entity):
+    """
+    Flexible markup/surcharge applied to shipping rates.
+
+    This is an admin-managed model (no user-level access control).
+    Use organization_ids JSONField to scope markups to specific organizations.
+    An empty organization_ids list means the markup applies system-wide.
+
+    Key changes from legacy Surcharge:
+    - Renamed from Surcharge to Markup
+    - Uses string lists instead of M2M/FK/enum relations
+    - connection_ids supports all connection types (account, system, brokered)
+    - carrier_codes and service_codes are validated strings, not enums
+    """
+
     class Meta:
-        db_table = "surcharge"
+        db_table = "markup"
         verbose_name = "Markup"
         verbose_name_plural = "Markups"
-
-    CONTEXT_RELATIONS = ["carrier_accounts"]
+        ordering = ["-created_at"]
 
     id = models.CharField(
         max_length=50,
         primary_key=True,
-        default=functools.partial(core.uuid, prefix="chrg_"),
+        default=functools.partial(core.uuid, prefix="mkp_"),
         editable=False,
     )
-    active = models.BooleanField(default=True)
-
     name = models.CharField(
         max_length=100,
         unique=True,
-        help_text="The surcharge name (label) that will appear in the rate (quote)",
+        help_text="The markup name (label) that will appear in the rate breakdown",
+    )
+    active = models.BooleanField(
+        default=True,
+        help_text="Whether the markup is active and will be applied to rates",
     )
     amount = models.FloatField(
-        validators=[validators.MinValueValidator(0.1)],
+        validators=[validators.MinValueValidator(0.0)],
         default=0.0,
         help_text="""
-        The surcharge amount or percentage to add to the quote
+        The markup amount or percentage to add to the quote.
+        For AMOUNT type: the exact dollar amount to add.
+        For PERCENTAGE type: the percentage (e.g., 5 means 5%).
         """,
     )
-    surcharge_type = models.CharField(
+    markup_type = models.CharField(
         max_length=25,
-        choices=serializers.SURCHAGE_TYPE,
-        default=serializers.SURCHAGE_TYPE[0][0],
+        choices=MARKUP_TYPE_CHOICES,
+        default=MARKUP_TYPE_CHOICES[0][0],
         help_text="""
-        Determine whether the surcharge is in percentage or net amount
-        <br/><br/>
-        For <strong>AMOUNT</strong>: rate ($22) and amount (1) will result in a new total_charge of ($23)
-        <br/>
-        For <strong>PERCENTAGE</strong>: rate ($22) and amount (5) will result in a new total_charge of ($23.10)
+        Determine whether the markup is in percentage or net amount.
+        AMOUNT: rate ($22) + amount (1) = $23
+        PERCENTAGE: rate ($22) * 5% = $23.10
         """,
     )
-    carriers = fields.MultiChoiceField(
-        choices=serializers.CARRIERS,
-        null=True,
+    is_visible = models.BooleanField(
+        default=True,
+        help_text="Whether to show this markup in the rate breakdown to users",
+    )
+
+    # Filters (all string lists, validated on save)
+    carrier_codes = models.JSONField(
+        default=list,
         blank=True,
         help_text="""
-        The list of carriers you want to apply the surcharge to.
-        <br/>
-        Note that by default, the surcharge is applied to all carriers
+        List of carrier codes to apply the markup to (e.g., ["fedex", "ups"]).
+        Empty list means apply to all carriers.
         """,
     )
-    carrier_accounts = models.ManyToManyField(
-        providers.Carrier,
+    service_codes = models.JSONField(
+        default=list,
         blank=True,
         help_text="""
-        The list of carrier accounts you want to apply the surcharge to.
-        <br/>
-        Note that by default, the surcharge is applied to all carrier accounts
+        List of service codes to apply the markup to (e.g., ["fedex_ground", "ups_next_day"]).
+        Empty list means apply to all services.
         """,
     )
-    services = fields.MultiChoiceField(
-        choices=serializers.SERVICES,
-        null=True,
+    connection_ids = models.JSONField(
+        default=list,
         blank=True,
         help_text="""
-        The list of services you want to apply the surcharge to.
-        <br/>
-        Note that by default, the surcharge is applied to all services
+        List of connection IDs to apply the markup to (e.g., ["car_xxx", "car_yyy"]).
+        Supports all connection types: CarrierConnection, SystemConnection, BrokeredConnection.
+        Empty list means apply to all connections.
         """,
     )
+    organization_ids = models.JSONField(
+        default=list,
+        blank=True,
+        help_text="""
+        List of organization IDs to apply the markup to.
+        Empty list means apply to all organizations (system-wide).
+        """,
+    )
+
+    # Metadata
+    metadata = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text="Additional metadata for the markup",
+    )
+
+    # Metafields via GenericRelation
+    metafields = GenericRelation(
+        "core.Metafield",
+        related_query_name="markup",
+    )
 
     @property
     def object_type(self):
-        return "surcharge"
+        return "markup"
 
     def __str__(self):
-        type_ = "$" if self.surcharge_type == "AMOUNT" else "%"
-        return f"{self.id} ({self.amount} {type_})"
+        type_ = "$" if self.markup_type == "AMOUNT" else "%"
+        return f"{self.name} ({self.amount}{type_})"
+
+    def _is_applicable(self, rate: datatypes.Rate) -> bool:
+        """Check if this markup should be applied to the given rate."""
+        applicable = []
+
+        # Check carrier code filter
+        if self.carrier_codes:
+            # For custom carriers (ext="generic"), check if "generic" is in the carrier list
+            if (
+                rate.meta
+                and rate.meta.get("ext") == "generic"
+                and "generic" in self.carrier_codes
+            ):
+                applicable.append(True)
+            else:
+                applicable.append(rate.carrier_name in self.carrier_codes)
+
+        # Check connection ID filter
+        if self.connection_ids:
+            connection_id = rate.meta.get("carrier_connection_id") if rate.meta else None
+            applicable.append(connection_id in self.connection_ids)
+
+        # Check service code filter
+        if self.service_codes:
+            applicable.append(rate.service in self.service_codes)
+
+        # All specified filters must match (AND logic)
+        # If no filters specified (all empty), markup applies to all rates
+        return (not applicable) or (any(applicable) and all(applicable))
 
     def apply_charge(self, response: datatypes.RateResponse) -> datatypes.RateResponse:
+        """Apply this markup to all applicable rates in the response."""
+
         def apply(rate: datatypes.Rate) -> datatypes.Rate:
-            applicable = []
-            carrier_ids = [c.carrier_id for c in self.carrier_accounts.all()]
-            charges = getattr(rate, "extra_charges", None) or []
-
-            if any(self.carriers or []):
-                # For custom carriers (ext="generic"), check if "generic" is in the addon's carrier list
-                # since rate.carrier_name contains custom_carrier_name but users select "generic"
-                if (
-                    rate.meta
-                    and rate.meta.get("ext") == "generic"
-                    and "generic" in self.carriers
-                ):
-                    applicable.append(True)
-                else:
-                    applicable.append(rate.carrier_name in self.carriers)
-
-            if any(carrier_ids):
-                applicable.append(rate.carrier_id in carrier_ids)
-
-            if any(self.services or []):
-                applicable.append(rate.service in self.services)
-
-            if any(applicable) and all(applicable):
-                logger.debug("Applying broker surcharge to rate", rate_id=rate.id, surcharge_id=self.id)
-
-                amount = lib.to_decimal(
-                    self.amount
-                    if self.surcharge_type == "AMOUNT"
-                    else (rate.total_charge * (typing.cast(float, self.amount) / 100))
-                )
-                total_charge = lib.to_decimal(rate.total_charge + amount)
-                extra_charges = rate.extra_charges + [
-                    karrio.ChargeDetails(
-                        name=typing.cast(str, self.name),
-                        amount=amount,
-                        currency=rate.currency,
-                        id=self.id,
-                    )
-                ]
-
-                return datatypes.Rate(
-                    **{
-                        **lib.to_dict(rate),
-                        "total_charge": total_charge,
-                        "extra_charges": extra_charges,
-                    }
+            if not self._is_applicable(rate):
+                return rate
+
+            logger.debug(
+                "Applying markup to rate",
+                rate_id=rate.id,
+                markup_id=self.id,
+                markup_name=self.name,
+            )
+
+            amount = lib.to_decimal(
+                self.amount
+                if self.markup_type == "AMOUNT"
+                else (rate.total_charge * (typing.cast(float, self.amount) / 100))
+            )
+            total_charge = lib.to_decimal(rate.total_charge + amount)
+            extra_charges = rate.extra_charges + [
+                karrio.ChargeDetails(
+                    name=typing.cast(str, self.name),
+                    amount=amount,
+                    currency=rate.currency,
+                    id=self.id,
                 )
+            ]
 
-            return rate
+            return datatypes.Rate(
+                **{
+                    **lib.to_dict(rate),
+                    "total_charge": total_charge,
+                    "extra_charges": extra_charges,
+                }
+            )
 
         return datatypes.RateResponse(
             messages=response.messages,
@@ -151,3 +217,118 @@ class Surcharge(core.ControlledAccessModel, core.Entity):
                 key=lambda rate: rate.total_charge,
             ),
         )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FEE MODEL (tracks applied markups for usage statistics)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class Fee(models.Model):
+    """
+    Immutable snapshot of an applied fee at time of shipment purchase.
+    Primary source of truth for usage statistics and financial reporting.
+
+    All reference fields are plain CharFields (no FKs) — this decouples
+    fee records from live objects so they survive deletions/changes.
+    """
+
+    class Meta:
+        db_table = "fee"
+        verbose_name = "Fee"
+        verbose_name_plural = "Fees"
+        ordering = ["-created_at"]
+        indexes = [
+            # Single-field indexes for fields without db_index=True
+            models.Index(fields=["carrier_code"]),
+            models.Index(fields=["created_at"]),
+            # Composite indexes for time-series queries
+            models.Index(fields=["account_id", "created_at"]),
+            models.Index(fields=["connection_id", "created_at"]),
+            models.Index(fields=["markup_id", "created_at"]),
+        ]
+
+    id = models.CharField(
+        max_length=50,
+        primary_key=True,
+        default=functools.partial(core.uuid, prefix="fee_"),
+        editable=False,
+    )
+
+    # Fee details (captured at time of application)
+    name = models.CharField(
+        max_length=100,
+        help_text="The fee name at time of application",
+    )
+    amount = models.FloatField(
+        help_text="The fee amount in the shipment's currency",
+    )
+    currency = models.CharField(
+        max_length=3,
+        help_text="Currency code (e.g., USD, EUR)",
+    )
+    fee_type = models.CharField(
+        max_length=25,
+        choices=MARKUP_TYPE_CHOICES,
+        help_text="Whether this was a fixed amount or percentage markup",
+    )
+    percentage = models.FloatField(
+        null=True,
+        blank=True,
+        help_text="Original percentage if this was a percentage-based markup",
+    )
+
+    # Markup reference (snapshot, no FK)
+    markup_id = models.CharField(
+        max_length=50,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="The markup ID that generated this fee",
+    )
+
+    # Shipment reference (snapshot, no FK)
+    shipment_id = models.CharField(
+        max_length=50,
+        db_index=True,
+        help_text="The shipment this fee was applied to",
+    )
+
+    # Organization/Account reference (snapshot, no FK)
+    account_id = models.CharField(
+        max_length=50,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="The organization/account this fee belongs to",
+    )
+
+    # Carrier connection context
+    connection_id = models.CharField(
+        max_length=50,
+        db_index=True,
+        help_text="Connection ID used for this shipment",
+    )
+    carrier_code = models.CharField(
+        max_length=50,
+        help_text="Carrier code at time of shipment creation",
+    )
+    service_code = models.CharField(
+        max_length=100,
+        null=True,
+        blank=True,
+        help_text="Service code at time of shipment creation",
+    )
+
+    # Context
+    test_mode = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return f"{self.name}: {self.amount} {self.currency}"
+
+    @property
+    def object_type(self):
+        return "fee"
+
+

karrio/server/pricing/serializers.py

@@ -1,18 +1,23 @@
+"""
+Pricing module serializers.
+
+This module provides simple constants and enums for markup types.
+The old enum-based CARRIERS and SERVICES are no longer used - markups
+now use plain string lists for carrier_codes and service_codes.
+"""
+
 import enum
-import karrio.server.core.dataunits as dataunits
-from karrio.server.core.serializers import (
-    CARRIERS,
-)
 
 
-class SurchargeType(enum.Enum):
+class MarkupType(enum.Enum):
+    """Type of markup to apply."""
     AMOUNT = "AMOUNT"
     PERCENTAGE = "PERCENTAGE"
 
 
-CARRIER_SERVICES = [
-    dataunits.REFERENCE_MODELS["services"][name]
-    for name in sorted(dataunits.REFERENCE_MODELS["services"].keys())
-]
-SERVICES = [(code, code) for services in CARRIER_SERVICES for code in services]
-SURCHAGE_TYPE = [(c.name, c.name) for c in list(SurchargeType)]
+# Markup type choices for Django model field
+MARKUP_TYPE = [(c.name, c.name) for c in list(MarkupType)]
+
+# Legacy aliases for backward compatibility
+SurchargeType = MarkupType
+SURCHAGE_TYPE = MARKUP_TYPE

karrio/server/pricing/signals.py

@@ -1,6 +1,16 @@
+"""
+Pricing module signals.
+
+This module provides:
+1. Rate post-processing to apply custom markups to shipping quotes
+2. Fee capture after shipment label creation
+"""
+
 import functools
 import importlib
 from django.db.models import Q
+from django.db.models.signals import post_save
+from django.dispatch import receiver
 
 from karrio.server.serializers import Context
 from karrio.server.core.gateway import Rates
@@ -8,26 +18,140 @@ from karrio.server.core.logging import logger
 import karrio.server.pricing.models as models
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# RATE POST-PROCESSING (Apply markups to quotes)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
 def register_rate_post_processing(*args, **kwargs):
-    Rates.post_process_functions += [apply_custom_surcharges]
-    logger.info("Signal registration complete", module="karrio.pricing")
+    """Register the markup application function for rate post-processing."""
+    Rates.post_process_functions += [apply_custom_markups]
+    logger.info("Markup rate post-processing registered", module="karrio.pricing")
+
+
+def apply_custom_markups(context: Context, result):
+    """
+    Apply active markups to rate quotes.
 
+    This function is called after rates are fetched from carriers.
+    It applies all active markups that match the organization context.
 
-def apply_custom_surcharges(context: Context, result):
-    _filters = tuple()
+    Markup scoping via organization_ids JSONField:
+    - Markups with org ID in organization_ids apply only to that org
+    - Markups with empty organization_ids are system-wide
+    """
+    org_id = getattr(context.org, "id", None)
 
-    if importlib.util.find_spec("karrio.server.orgs") is not None:
-        _filters += (
-            Q(active=True, org__id=getattr(context.org, "id", None))
-            | Q(active=True, org=None),
+    if org_id:
+        # Filter markups that either:
+        # 1. Have the current organization in their organization_ids list
+        # 2. Have an empty organization_ids list (system-wide markups)
+        _filters = (
+            Q(active=True, organization_ids__contains=[org_id])
+            | Q(active=True, organization_ids=[]),
         )
     else:
-        _filters += (Q(active=True),)
+        # No organization context - only apply system-wide markups
+        _filters = (Q(active=True, organization_ids=[]),)
 
-    charges = models.Surcharge.objects.filter(*_filters)
+    markups = models.Markup.objects.filter(*_filters)
 
     return functools.reduce(
-        lambda cummulated_result, charge: charge.apply_charge(cummulated_result),
-        charges,
+        lambda cumulated_result, markup: markup.apply_charge(cumulated_result),
+        markups,
         result,
     )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FEE CAPTURE (Record fees after shipment creation)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def capture_fees_for_shipment(shipment):
+    """
+    Capture fee records for all markups applied to a shipment.
+
+    This function extracts markup charges from the shipment's selected_rate
+    and creates Fee snapshot records for usage statistics and reporting.
+    All fields are captured as plain values (no FK references).
+    """
+    if not shipment.selected_rate:
+        return
+
+    selected_rate = shipment.selected_rate
+    extra_charges = selected_rate.get("extra_charges", [])
+    meta = selected_rate.get("meta", {}) or {}
+    carrier_code = meta.get("carrier_code") or selected_rate.get("carrier_name", "")
+    service_code = selected_rate.get("service", "")
+    connection_id = meta.get("carrier_connection_id", "") or meta.get("connection_id", "")
+    currency = selected_rate.get("currency", "USD")
+    test_mode = getattr(shipment, "test_mode", False)
+
+    # Resolve account/org ID from shipment's org link
+    account_id = None
+    if hasattr(shipment, "org"):
+        _org = shipment.org.first()
+        account_id = getattr(_org, "id", None)
+
+    for charge in extra_charges:
+        charge_id = charge.get("id")
+
+        # Only capture charges that have IDs starting with 'mkp_' (our markups)
+        # or 'chrg_' (legacy surcharges)
+        if not charge_id or not (charge_id.startswith("mkp_") or charge_id.startswith("chrg_")):
+            continue
+
+        # Look up markup for fee_type/percentage snapshot
+        markup = models.Markup.objects.filter(id=charge_id).first()
+
+        # Create fee snapshot record (no FK references)
+        try:
+            models.Fee.objects.create(
+                shipment_id=shipment.id,
+                markup_id=charge_id,
+                account_id=account_id,
+                test_mode=test_mode,
+                name=charge.get("name", ""),
+                amount=charge.get("amount", 0),
+                currency=currency,
+                fee_type=markup.markup_type if markup else "AMOUNT",
+                percentage=markup.amount if markup and markup.markup_type == "PERCENTAGE" else None,
+                carrier_code=carrier_code,
+                service_code=service_code,
+                connection_id=connection_id,
+            )
+            logger.debug(
+                "Fee captured for shipment",
+                shipment_id=shipment.id,
+                markup_id=charge_id,
+                amount=charge.get("amount"),
+            )
+        except Exception as e:
+            logger.warning(
+                "Failed to capture fee for shipment",
+                shipment_id=shipment.id,
+                charge_id=charge_id,
+                error=str(e),
+            )
+
+
+def register_fee_capture(*args, **kwargs):
+    """Register the fee capture signal for shipment post-save."""
+    # Import here to avoid circular imports
+    import karrio.server.manager.models as manager
+
+    @receiver(post_save, sender=manager.Shipment)
+    def on_shipment_saved(sender, instance, created, **kwargs):
+        """Capture fees when a shipment is created or updated with a selected rate."""
+        # Only capture fees when:
+        # 1. Shipment has a selected_rate (label was purchased)
+        # 2. Shipment status indicates it's been purchased/processed
+        if instance.selected_rate and instance.status not in ["draft", "created"]:
+            # Check if we've already captured fees for this shipment
+            if not models.Fee.objects.filter(shipment_id=instance.id).exists():
+                capture_fees_for_shipment(instance)
+
+    logger.info("Fee capture signal registered", module="karrio.pricing")
+
+