karrio-server-core 2025.5rc12__py3-none-any.whl → 2026.1.1__py3-none-any.whl

karrio/server/core/serializers.py

@@ -21,6 +21,7 @@ class ShipmentStatus(utils.Enum):
 
 class TrackerStatus(utils.Enum):
     pending = "pending"
+    picked_up = "picked_up"
     unknown = "unknown"
     on_hold = "on_hold"
     cancelled = "cancelled"
@@ -49,6 +50,9 @@ CUSTOMS_CONTENT_TYPE = [(c.name, c.name) for c in list(units.CustomsContentType)
 UPLOAD_DOCUMENT_TYPE = [(c.name, c.name) for c in list(units.UploadDocumentType)]
 LABEL_TYPES = [(c.name, c.name) for c in list(units.LabelType)]
 LABEL_TEMPLATE_TYPES = [("SVG", "SVG"), ("ZPL", "ZPL")]
+TRACKING_INCIDENT_REASONS = [
+    (c.name, c.name) for c in list(units.TrackingIncidentReason)
+]
 
 
 class CarrierDetails(serializers.Serializer):
@@ -129,6 +133,7 @@ class APIError(serializers.Serializer):
         required=False, help_text="The error or warning message"
     )
     code = serializers.CharField(required=False, help_text="The message code")
+    level = serializers.CharField(required=False, help_text="The message level")
     details = serializers.DictField(required=False, help_text="any additional details")
 
 
@@ -153,7 +158,7 @@ class AddressData(validators.AugmentedAddressSerializer):
         required=False,
         allow_blank=True,
         allow_null=True,
-        max_length=10,
+        max_length=20,
         help_text="""The address postal code
         **(required for shipment purchase)**
         """,
@@ -323,6 +328,26 @@ class CommodityData(serializers.Serializer):
         choices=COUNTRIES,
         help_text="The origin or manufacture country",
     )
+    product_url = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="The product url",
+    )
+    image_url = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="The image url",
+    )
+    product_id = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="The product id",
+    )
+    variant_id = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="The variant id",
+    )
     parent_id = serializers.CharField(
         required=False,
         allow_null=True,
@@ -372,7 +397,7 @@ class ParcelData(validators.PresetSerializer):
         required=False,
         allow_blank=True,
         allow_null=True,
-        max_length=50,
+        max_length=100,
         help_text=f"""The parcel's packaging type.<br/>
         **Note that the packaging is optional when using a package preset.**<br/>
         values: <br/>
@@ -384,7 +409,7 @@ class ParcelData(validators.PresetSerializer):
         required=False,
         allow_blank=True,
         allow_null=True,
-        max_length=50,
+        max_length=100,
         help_text="""The parcel's package preset.<br/>
         For carrier specific package presets, please consult the reference.
         """,
@@ -613,6 +638,12 @@ class Charge(serializers.Serializer):
         allow_null=True,
         help_text="The charge amount currency",
     )
+    id = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="A surcharge id",
+    )
 
 
 @serializers.allow_model_id(
@@ -660,6 +691,7 @@ class RateRequest(validators.OptionDefaultSerializer):
         {
             "currency": "USD",
             "insurance": 100.00,
+            "insured_by": "carrier",
             "cash_on_delivery": 30.00,
             "dangerous_good": true,
             "declared_value": 150.00,
@@ -701,6 +733,18 @@ class RateRequest(validators.OptionDefaultSerializer):
         allow_null=True,
         help_text="The shipment reference",
     )
+    payment = Payment(
+        required=False,
+        allow_null=True,
+        help_text="The payment details",
+    )
+    customs = CustomsData(
+        required=False,
+        allow_null=True,
+        help_text="""The customs details.<br/>
+        **Note that this is required for international shipments.**
+        """,
+    )
     carrier_ids = serializers.StringListField(
         required=False,
         allow_null=True,
@@ -1042,11 +1086,24 @@ class TrackingEvent(serializers.Serializer):
     date = serializers.CharField(
         required=False, help_text="The tracking event's date. Format: `YYYY-MM-DD`"
     )
-    description = serializers.CharField(
-        required=False, help_text="The tracking event's description"
+    time = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The tracking event's time. Format: `HH:MM AM/PM`",
     )
-    location = serializers.CharField(
-        required=False, help_text="The tracking event's location"
+    timestamp = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The tracking event's timestamp. Format: `YYYY-MM-DDTHH:MM:SS.sssZ` (ISO 8601)",
+    )
+    status = serializers.ChoiceField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        choices=TRACKER_STATUS,
+        help_text="The normalized status of this specific event",
     )
     code = serializers.CharField(
         required=False,
@@ -1054,11 +1111,18 @@ class TrackingEvent(serializers.Serializer):
         allow_null=True,
         help_text="The tracking event's code",
     )
-    time = serializers.CharField(
+    reason = serializers.ChoiceField(
         required=False,
         allow_blank=True,
         allow_null=True,
-        help_text="The tracking event's time. Format: `HH:MM AM/PM`",
+        choices=TRACKING_INCIDENT_REASONS,
+        help_text="The normalized incident reason (for exception events only)",
+    )
+    description = serializers.CharField(
+        required=False, help_text="The tracking event's description"
+    )
+    location = serializers.CharField(
+        required=False, help_text="The tracking event's location"
     )
     latitude = serializers.FloatField(
         required=False,
@@ -1153,6 +1217,62 @@ class TrackingStatus(TrackerDetails):
     )
 
 
+class ShippingDocument(serializers.Serializer):
+    """Serializer for shipping document download response."""
+
+    category = serializers.CharField(
+        required=True,
+        help_text="The document category (e.g., 'label', 'invoice', 'manifest')",
+    )
+    format = serializers.CharField(
+        required=True,
+        help_text="The document format (e.g., 'PDF', 'ZPL')",
+    )
+    url = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The document URL",
+    )
+    base64 = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The document content encoded in base64",
+    )
+
+
+class ShippingDocument(serializers.Serializer):
+    """Serializer for shipping document download response."""
+
+    category = serializers.CharField(
+        required=True,
+        help_text="The document category (e.g., 'label', 'invoice', 'manifest')",
+    )
+    format = serializers.CharField(
+        required=True,
+        help_text="The document format (e.g., 'PDF', 'ZPL')",
+    )
+    print_format = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The document print format (e.g., 'A4', '6x4', '8.5x11')",
+    )
+    url = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The document URL",
+    )
+    base64 = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The document content encoded in base64",
+    )
+
+
 class Documents(serializers.Serializer):
     label = serializers.CharField(
         required=False,
@@ -1585,6 +1705,7 @@ class ShipmentContent(serializers.Serializer):
     )
 
 
+@validators.shipment_documents_accessor
 class Shipment(serializers.EntitySerializer, ShipmentContent, ShipmentDetails):
     docs = None
     label_url = serializers.URLField(
@@ -1599,6 +1720,12 @@ class Shipment(serializers.EntitySerializer, ShipmentContent, ShipmentDetails):
         allow_null=True,
         help_text="The shipment invoice URL",
     )
+    shipping_documents = ShippingDocument(
+        required=False,
+        many=True,
+        default=[],
+        help_text="The list of shipping documents",
+    )
 
 
 class ShipmentCancelRequest(serializers.Serializer):
@@ -1750,7 +1877,10 @@ class OperationConfirmation(Operation):
         required=True, help_text="The operation carrier"
     )
     carrier_id = serializers.CharField(
-        required=True, help_text="The targeted carrier's name (unique identifier)"
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="The targeted carrier's name (unique identifier)",
     )
 
 
@@ -1887,6 +2017,49 @@ class DocumentUploadRecord(serializers.EntitySerializer):
     )
 
 
+class OAuthAuthorizeData(serializers.Serializer):
+    """OAuth authorization request data serializer."""
+
+    state = serializers.CharField(
+        required=True,
+        help_text="A unique state value for CSRF protection.",
+    )
+    redirect_uri = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="The URI to redirect to after authorization.",
+    )
+    options = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Additional carrier-specific options.",
+    )
+
+
+class OAuthCallbackData(serializers.Serializer):
+    """OAuth callback request data serializer."""
+
+    url = serializers.CharField(
+        required=True,
+        help_text="The full callback URL.",
+    )
+    query = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="The query parameters from the callback URL.",
+    )
+    body = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="The request body if any.",
+    )
+    headers = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="The request headers.",
+    )
+
+
 class ErrorMessages(serializers.Serializer):
     messages = Message(
         many=True,

karrio/server/core/signals.py

@@ -1,57 +1,51 @@
-import logging
 from django.conf import settings
 from django.dispatch import receiver
 from constance import config
 from constance.signals import config_updated
 from django.core.signals import request_started
 
-logger = logging.getLogger(__name__)
+from karrio.server.core.logging import logger
 
 
 def register_signals():
     config_updated.connect(constance_updated)
-    # Defer config initialization until after Django is fully loaded
     request_started.connect(initialize_settings)
 
-    logger.info("karrio.core signals registered...")
+    logger.info("Signal registration complete", module="karrio.core")
 
 
-def initialize_settings(sender=None, **kwargs):
-    # Only run once
-    if not getattr(initialize_settings, 'has_run', False):
-        try:
-            update_settings(config)
-            initialize_settings.has_run = True
-        except Exception as e:
-            logger.error(f"Failed to initialize settings: {e}")
+def initialize_settings(_sender=None, **_kwargs):
+    """Initialize Django settings from constance on first request."""
+    if getattr(initialize_settings, "has_run", False):
+        return
+
+    try:
+        update_settings(config)
+        initialize_settings.has_run = True
+    except Exception as e:
+        logger.error("Failed to initialize settings", error=str(e))
 
 
 @receiver(config_updated)
-def constance_updated(sender, key, old_value, new_value, **kwargs):
-    logger.info(f"Updated config {key} to {new_value}")
+def constance_updated(sender, **_kwargs):
     update_settings(sender)
 
 
 def update_settings(current):
-    CONSTANCE_CONFIG_KEYS = [
-        key for key in settings.CONSTANCE_CONFIG.keys() if hasattr(settings, key)
-    ]
+    """Sync constance values to Django settings."""
+    keys = [k for k in settings.CONSTANCE_CONFIG.keys() if hasattr(settings, k)]
 
-    for key in CONSTANCE_CONFIG_KEYS:
+    for key in keys:
         try:
             setattr(settings, key, getattr(current, key))
-        except Exception as e:
-            logger.error(f"Failed to update setting {key}: {e}")
+        except Exception:
+            pass  # Ignore errors during test/initialization when constance table may not exist
 
-    # Check EMAIL_ENABLED after all settings are updated
+    # Update EMAIL_ENABLED based on email config
     try:
         settings.EMAIL_ENABLED = all(
-            cfg is not None and cfg != ""
-            for cfg in [
-                current.EMAIL_HOST,
-                current.EMAIL_HOST_USER,
-            ]
+            cfg not in (None, "")
+            for cfg in [current.EMAIL_HOST, current.EMAIL_HOST_USER]
         )
-    except Exception as e:
-        logger.error(f"Failed to set EMAIL_ENABLED: {e}")
+    except Exception:
         settings.EMAIL_ENABLED = False