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

karrio/server/core/gateway.py

@@ -1,12 +1,12 @@
 import uuid
 import typing
-import logging
 import datetime
 
 from django.db.models import Q
 from django.conf import settings
 from rest_framework import status
 from rest_framework.exceptions import NotFound
+from karrio.server.core.logging import logger
 
 import karrio.lib as lib
 import karrio.sdk as karrio
@@ -14,14 +14,11 @@ import karrio.server.core.utils as utils
 import karrio.server.core.models as core
 import karrio.server.core.datatypes as datatypes
 import karrio.server.core.dataunits as dataunits
-import karrio.server.core.validators as validators
 import karrio.server.core.exceptions as exceptions
 import karrio.server.providers.models as providers
 import karrio.server.serializers as base_serializers
 import karrio.server.core.serializers as serializers
 
-logger = logging.getLogger(__name__)
-
 
 class Carriers:
     @staticmethod
@@ -133,17 +130,36 @@ class Carriers:
 
 class Address:
     @staticmethod
-    def validate(payload: dict) -> datatypes.AddressValidation:
-        validation = validators.Address.validate(datatypes.Address(**payload))
+    @utils.with_telemetry("address_validate")
+    def validate(
+        payload: dict,
+        provider: providers.Carrier = None,
+        **carrier_filters,
+    ) -> datatypes.AddressValidation:
+        provider = provider or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **carrier_filters,
+            }
+        )
+
+        if "validate_address" not in provider.gateway.proxy_methods:
+            raise exceptions.APIException(
+                detail=f"address validation is not supported by carrier: '{provider.carrier_id}'",
+                status_code=status.HTTP_406_NOT_ACCEPTABLE,
+            )
 
-        if validation.success is False:
-            raise exceptions.APIException(detail=validation, code="invalid_address")
+        request = karrio.Address.validate(
+            lib.to_object(datatypes.AddressValidationRequest, payload)
+        )
 
-        return validation
+        # The request is wrapped in utils.identity to simplify mocking in tests.
+        return utils.identity(lambda: request.from_(provider.gateway).parse())
 
 
 class Shipments:
     @staticmethod
+    @utils.with_telemetry("shipment_create")
     @utils.require_selected_rate
     def create(
         payload: dict,
@@ -167,9 +183,19 @@ class Shipments:
         if carrier is None:
             raise NotFound("No active carrier connection found to process the request")
 
+        payload = {
+            **lib.to_dict(payload),
+            "options": {
+                **(selected_rate.meta or {}),
+                **(payload.get("options") or {}),
+            },
+        }
         request = lib.to_object(
             datatypes.ShipmentRequest,
-            {**lib.to_dict(payload), "service": selected_rate.service},
+            {
+                **lib.to_dict(payload),
+                "service": selected_rate.service,
+            },
         )
 
         # The request is wrapped in utils.identity to simplify mocking in tests.
@@ -198,7 +224,11 @@ class Shipments:
                 "carrier": rate_provider,
                 "service_name": service_name,
                 "rate_provider": rate_provider,  # TODO: deprecate 'rate_provider' in favor of 'carrier'
-                **({"custom_carrier_name": custom_carrier_name} if custom_carrier_name else {}),
+                **(
+                    {"custom_carrier_name": custom_carrier_name}
+                    if custom_carrier_name
+                    else {}
+                ),
             }
 
         def process_selected_rate() -> dict:
@@ -288,6 +318,7 @@ class Shipments:
         )
 
     @staticmethod
+    @utils.with_telemetry("shipment_cancel")
     def cancel(
         payload: dict, carrier: providers.Carrier = None, **carrier_filters
     ) -> datatypes.ConfirmationResponse:
@@ -338,6 +369,7 @@ class Shipments:
         )
 
     @staticmethod
+    @utils.with_telemetry("tracking_fetch")
     def track(
         payload: dict,
         carrier: providers.Carrier = None,
@@ -427,6 +459,7 @@ class Shipments:
 
 class Pickups:
     @staticmethod
+    @utils.with_telemetry("pickup_schedule")
     def schedule(
         payload: dict, carrier: providers.Carrier = None, **carrier_filters
     ) -> datatypes.PickupResponse:
@@ -476,6 +509,7 @@ class Pickups:
         )
 
     @staticmethod
+    @utils.with_telemetry("pickup_update")
     def update(
         payload: dict, carrier: providers.Carrier = None, **carrier_filters
     ) -> datatypes.PickupResponse:
@@ -516,6 +550,7 @@ class Pickups:
         )
 
     @staticmethod
+    @utils.with_telemetry("pickup_cancel")
     def cancel(
         payload: dict, carrier: providers.Carrier = None, **carrier_filters
     ) -> datatypes.ConfirmationResponse:
@@ -564,6 +599,7 @@ class Rates:
     post_process_functions: typing.List[typing.Callable] = []
 
     @staticmethod
+    @utils.with_telemetry("rates_fetch")
     def fetch(
         payload: dict,
         carriers: typing.List[providers.Carrier] = None,
@@ -642,6 +678,7 @@ class Rates:
 
 class Documents:
     @staticmethod
+    @utils.with_telemetry("document_upload")
     def upload(
         payload: dict,
         carrier: providers.Carrier = None,
@@ -689,6 +726,7 @@ class Documents:
 
 class Manifests:
     @staticmethod
+    @utils.with_telemetry("manifest_create")
     def create(
         payload: dict, carrier: providers.Carrier = None, **carrier_filters
     ) -> datatypes.ManifestResponse:
@@ -736,3 +774,238 @@ class Manifests:
             ),
             messages=messages,
         )
+
+
+class Insurance:
+    @staticmethod
+    @utils.with_telemetry("insurance_apply")
+    def apply(
+        payload: dict, provider: providers.Carrier = None, **provider_filters
+    ) -> datatypes.InsuranceDetails:
+        provider = provider or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **provider_filters,
+            }
+        )
+
+        if "apply_insurance" not in provider.gateway.proxy_methods:
+            raise exceptions.APIException(
+                detail=f"insurance application is not supported by carrier: '{provider.carrier_id}'",
+                status_code=status.HTTP_406_NOT_ACCEPTABLE,
+            )
+
+        request = karrio.Insurance.apply(
+            lib.to_object(datatypes.InsuranceRequest, payload)
+        )
+
+        # The request call is wrapped in utils.identity to simplify mocking in tests
+        insurance, messages = utils.identity(
+            lambda: request.from_(provider.gateway).parse()
+        )
+
+        if insurance is None:
+            raise exceptions.APIException(
+                detail=messages,
+                status_code=status.HTTP_424_FAILED_DEPENDENCY,
+            )
+
+        def process_meta(parent) -> dict:
+            return {
+                **(parent.meta or {}),
+                "ext": provider.ext,
+            }
+
+        return datatypes.InsuranceResponse(
+            insurance=datatypes.Insurance(
+                **{
+                    **payload,
+                    **lib.to_dict(insurance),
+                    "id": f"ins_{uuid.uuid4().hex}",
+                    "test_mode": provider.test_mode,
+                    "meta": process_meta(insurance),
+                    "messages": messages,
+                }
+            ),
+            messages=messages,
+        )
+
+
+class Duties:
+    @staticmethod
+    @utils.with_telemetry("duties_calculate")
+    def calculate(
+        payload: dict,
+        provider: providers.Carrier = None,
+        **provider_filters,
+    ) -> datatypes.DutiesResponse:
+        provider = provider or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **provider_filters,
+            }
+        )
+
+        if "calculate_duties" not in provider.gateway.proxy_methods:
+            raise exceptions.APIException(
+                detail=f"duties calculation is not supported by carrier: '{provider.carrier_id}'",
+                status_code=status.HTTP_406_NOT_ACCEPTABLE,
+            )
+
+        request = karrio.Duty.calculate(
+            lib.to_object(datatypes.DutiesCalculationRequest, payload)
+        )
+
+        # The request is wrapped in utils.identity to simplify mocking in tests.
+        duties, messages = utils.identity(
+            lambda: request.from_(provider.gateway).parse()
+        )
+
+        if duties is None:
+            raise exceptions.APIException(
+                detail=messages,
+                status_code=status.HTTP_424_FAILED_DEPENDENCY,
+            )
+
+        return datatypes.DutiesResponse(duties=duties, messages=messages)
+
+
+class Webhooks:
+    @staticmethod
+    @utils.with_telemetry("webhook_register")
+    def register(
+        payload: dict,
+        carrier: providers.Carrier = None,
+        **carrier_filters,
+    ) -> datatypes.DocumentUploadResponse:
+        carrier = carrier or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **carrier_filters,
+            }
+        )
+
+        if "register_webhook" not in carrier.gateway.proxy_methods:
+            raise exceptions.APIException(
+                detail=f"webhook registration is not supported by carrier: '{carrier.carrier_id}'",
+                status_code=status.HTTP_406_NOT_ACCEPTABLE,
+            )
+
+        request = karrio.Webhook.register(
+            lib.to_object(datatypes.WebhookRegistrationRequest, payload)
+        )
+
+        # The request is wrapped in utils.identity to simplify mocking in tests.
+        return utils.identity(lambda: request.from_(carrier.gateway).parse())
+
+    @staticmethod
+    @utils.with_telemetry("webhook_unregister")
+    def unregister(
+        payload: dict,
+        carrier: providers.Carrier = None,
+        **carrier_filters,
+    ) -> datatypes.ConfirmationResponse:
+        carrier = carrier or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **carrier_filters,
+            }
+        )
+
+        if "deregister_webhook" not in carrier.gateway.proxy_methods:
+            raise exceptions.APIException(
+                detail=f"webhook deregistration is not supported by carrier: '{carrier.carrier_id}'",
+                status_code=status.HTTP_406_NOT_ACCEPTABLE,
+            )
+
+        request = karrio.Webhook.deregister(
+            lib.to_object(datatypes.WebhookDeregistrationRequest, payload)
+        )
+
+        # The request is wrapped in utils.identity to simplify mocking in tests.
+        return utils.identity(lambda: request.from_(carrier.gateway).parse())
+
+
+class Hooks:
+
+    @staticmethod
+    def create_stub_gateway(
+        carrier_name: str, test_mode: bool = False
+    ) -> karrio.Gateway:
+        import karrio.server.core.middleware as middleware
+        import karrio.server.core.config as system_config
+        import django.core.cache as caching
+
+        _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[carrier_name].create(
+            dict(
+                carrier_id=carrier_name,
+                test_mode=test_mode,
+            ),
+            _tracer,
+            _cache,
+            _config,
+            is_stub=True,
+        )
+
+    @staticmethod
+    @utils.with_telemetry("hook_webhook_event")
+    def on_webhook_event(
+        payload: dict, carrier: providers.Carrier = None, **carrier_filters
+    ) -> typing.Tuple[datatypes.WebhookEventDetails, typing.List[datatypes.Message]]:
+        carrier = carrier or Carriers.first(
+            **{
+                **dict(active=True, raise_not_found=True),
+                **carrier_filters,
+            }
+        )
+
+        if carrier is None:
+            raise NotFound("No active carrier connection found to process the request")
+
+        request = karrio.Hooks.on_webhook_event(
+            lib.to_object(datatypes.RequestPayload, lib.to_dict(payload))
+        )
+
+        # The request call is wrapped in utils.identity to simplify mocking in tests
+        return utils.identity(lambda: request.from_(carrier.gateway).parse())
+
+    @staticmethod
+    @utils.with_telemetry("hook_oauth_authorize")
+    def on_oauth_authorize(
+        payload: dict,
+        carrier: providers.Carrier = None,
+        carrier_name: str = None,
+        test_mode: bool = False,
+        **kwargs,
+    ) -> typing.Tuple[datatypes.OAuthAuthorizeRequest, typing.List[datatypes.Message]]:
+        gateway = lib.identity(
+            getattr(carrier, "gateway", None)
+            or Hooks.create_stub_gateway(carrier_name, test_mode)
+        )
+
+        return utils.identity(
+            lambda: karrio.Hooks.on_oauth_authorize(payload).from_(gateway).parse()
+        )
+
+    @staticmethod
+    @utils.with_telemetry("hook_oauth_callback")
+    def on_oauth_callback(
+        payload: dict,
+        carrier_name: str = None,
+        test_mode: bool = False,
+        carrier: providers.Carrier = None,
+        **kwargs,
+    ) -> typing.Tuple[typing.List[typing.Dict], typing.List[datatypes.Message]]:
+        gateway = lib.identity(
+            getattr(carrier, "gateway", None)
+            or Hooks.create_stub_gateway(carrier_name, test_mode)
+        )
+
+        return utils.identity(
+            lambda: karrio.Hooks.on_oauth_callback(payload).from_(gateway).parse()
+        )