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

karrio/server/providers/views/carriers.py

@@ -1,6 +1,5 @@
 import io
 import base64
-import logging
 import re
 from django.http import JsonResponse
 from django.urls import path, re_path
@@ -15,9 +14,8 @@ import karrio.server.openapi as openapi
 import karrio.server.samples as samples
 import karrio.server.core.views.api as api
 import karrio.server.providers.models as models
+from karrio.server.core.logging import logger
 from karrio.server.core import datatypes, dataunits, serializers
-
-logger = logging.getLogger(__name__)
 ENDPOINT_ID = "&&"  # This endpoint id is used to make operation ids unique make sure not to duplicate
 
 

karrio/server/providers/views/connections.py

@@ -1,4 +1,3 @@
-import logging
 import django.urls as urls
 import rest_framework.status as status
 import rest_framework.request as request
@@ -14,7 +13,6 @@ import karrio.server.core.gateway as gateway
 import karrio.server.providers.models as models
 import karrio.server.providers.serializers as serializers
 
-logger = logging.getLogger(__name__)
 ENDPOINT_ID = "&&&"  # This endpoint id is used to make operation ids unique make sure not to duplicate
 CarrierConnectionList = serializers.PaginatedResult(
     "CarrierConnectionList", serializers.CarrierConnection
@@ -162,6 +160,298 @@ class CarrierConnectionDetail(api.APIView):
         return response.Response(serializers.CarrierConnection(connection).data)
 
 
+class ConnectionWebhookRegister(api.APIView):
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}webhook-register",
+        extensions={"x-operationId": "webhookRegister"},
+        summary="Register a webhook for a carrier connection",
+        request=serializers.WebhookRegisterData(),
+        responses={
+            200: serializers.WebhookOperationResponse(),
+            400: serializers.ErrorResponse(),
+            424: serializers.ErrorMessages(),
+        },
+    )
+    def post(self, request: request.Request, pk: str):
+        """Register a webhook endpoint for a carrier connection."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+        webhook_url = request.build_absolute_uri(f"/v1/connections/webhook/{pk}/events")
+
+        webhook_details = (
+            serializers.WebhookRegisterSerializer.map(
+                connection,
+                data={"webhook_url": webhook_url, **request.data},
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        updated = lib.identity(
+            serializers.CarrierConnectionModelSerializer.map(
+                connection,
+                data=dict(
+                    config=dict(
+                        webhook_id=webhook_details.webhook_identifier,
+                        webhook_secret=webhook_details.secret,
+                        webhook_url=webhook_url,
+                    )
+                ),
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        return response.Response(
+            serializers.WebhookOperationResponse(
+                dict(
+                    carrier_name=updated.carrier_name,
+                    carrier_id=updated.carrier_id,
+                    operation="Webhook registration",
+                    success=True,
+                )
+            ).data,
+            status=status.HTTP_200_OK,
+        )
+
+
+class ConnectionWebhookDeregister(api.APIView):
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}webhook-deregister",
+        extensions={"x-operationId": "webhookDeregister"},
+        summary="Deregister a webhook for a carrier connection",
+        responses={
+            200: serializers.WebhookOperationResponse(),
+            400: serializers.ErrorResponse(),
+            424: serializers.ErrorMessages(),
+        },
+    )
+    def post(self, request: request.Request, pk: str):
+        """Deregister a webhook endpoint from a carrier connection."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+
+        serializers.WebhookDeregisterSerializer.map(
+            connection,
+            data=dict(webhook_id=connection.config.get("webhook_id")),
+            context=request,
+        ).save()
+
+        updated = lib.identity(
+            serializers.CarrierConnectionModelSerializer.map(
+                connection,
+                data=dict(
+                    config=dict(
+                        webhook_id=None,
+                        webhook_secret=None,
+                        webhook_url=None,
+                    )
+                ),
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        return response.Response(
+            serializers.WebhookOperationResponse(
+                dict(
+                    operation="Webhook deregistration",
+                    success=True,
+                    carrier_name=updated.carrier_name,
+                    carrier_id=updated.carrier_id,
+                )
+            ).data,
+            status=status.HTTP_200_OK,
+        )
+
+
+class ConnectionWebhookDisconnect(api.APIView):
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}webhook-disconnect",
+        extensions={"x-operationId": "webhookDisconnect"},
+        summary="Force disconnect a webhook for a carrier connection",
+        responses={
+            200: serializers.WebhookOperationResponse(),
+            400: serializers.ErrorResponse(),
+        },
+    )
+    def post(self, request: request.Request, pk: str):
+        """Force disconnect a webhook from a carrier connection (local only)."""
+        connection = models.Carrier.access_by(request).get(pk=pk)
+
+        updated = lib.identity(
+            serializers.CarrierConnectionModelSerializer.map(
+                connection,
+                data=dict(
+                    config=dict(
+                        webhook_id=None,
+                        webhook_secret=None,
+                        webhook_url=None,
+                    )
+                ),
+                context=request,
+            )
+            .save()
+            .instance
+        )
+
+        return response.Response(
+            serializers.WebhookOperationResponse(
+                dict(
+                    operation="Webhook disconnect",
+                    success=True,
+                    carrier_name=updated.carrier_name,
+                    carrier_id=updated.carrier_id,
+                )
+            ).data,
+            status=status.HTTP_200_OK,
+        )
+
+
+class ConnectionWebhookEvent(api.APIView):
+    """Handle inbound webhook events from carriers."""
+
+    throttle_classes: list = []
+    permission_classes: list = []
+    authentication_classes: list = []
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}webhook-event",
+        extensions={"x-operationId": "webhookEvent"},
+        summary="Handle carrier webhook events",
+        responses={
+            200: serializers.OperationConfirmation(),
+        },
+    )
+    def post(self, request: request.Request, pk: str):
+        """Handle inbound webhook events from a carrier via POST."""
+        data, http_status = serializers.WebhookEventSerializer.process_event(
+            request, pk
+        )
+        return response.Response(data, status=http_status)
+
+
+class ConnectionOauthAuthorize(api.APIView):
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}oauth-authorize",
+        extensions={"x-operationId": "oauthAuthorize"},
+        summary="Handle an OAuth authorize",
+        request=serializers.OAuthAuthorizeData(),
+    )
+    def post(self, request: request.Request, carrier_name: str):
+        """Handle an OAuth authorize."""
+
+        [output, messages] = gateway.Hooks.on_oauth_authorize(
+            serializers.OAuthAuthorizeData.map(
+                data={
+                    "redirect_uri": request.build_absolute_uri(
+                        f"/v1/connections/oauth/{carrier_name}/callback"
+                    ),
+                    **request.data,
+                }
+            ).data,
+            carrier_name=carrier_name,
+            test_mode=request.test_mode,
+        )
+
+        # Include the frontend_url for the callback to redirect to
+        frontend_url = request.data.get("frontend_url")
+
+        return response.Response(
+            dict(
+                operation="OAuth authorize",
+                request=lib.to_dict(output),
+                messages=lib.to_dict(messages),
+                frontend_url=frontend_url,
+            ),
+            status=status.HTTP_200_OK,
+        )
+
+
+class ConnectionOauthCallback(api.APIView):
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}oauth-callback",
+        extensions={"x-operationId": "oauthCallback"},
+        summary="Handle an OAuth callback",
+        request=serializers.OAuthCallbackData(),
+        responses={
+            200: serializers.OperationConfirmation(),
+        },
+    )
+    def get(self, request: request.Request, carrier_name: str):
+        """Handle an OAuth callback via GET."""
+        return self._handle_callback(request, carrier_name)
+
+    @openapi.extend_schema(
+        exclude=True,
+        tags=["Connections"],
+        operation_id=f"{ENDPOINT_ID}oauth-callback-post",
+        extensions={"x-operationId": "oauthCallbackPost"},
+        summary="Handle an OAuth callback via POST",
+        request=serializers.OAuthCallbackData(),
+        responses={
+            200: serializers.OperationConfirmation(),
+        },
+    )
+    def post(self, request: request.Request, carrier_name: str):
+        """Handle an OAuth callback via POST."""
+        return self._handle_callback(request, carrier_name)
+
+    def _handle_callback(self, request: request.Request, carrier_name: str):
+        """Handle OAuth callback processing.
+
+        Returns JSON with OAuth result for the frontend to process.
+        When called from a browser popup, renders template or redirects to frontend.
+        """
+        import json
+        import base64
+        from django.shortcuts import render
+        from django.http import HttpResponseRedirect
+
+        result, frontend_url = serializers.OAuthCallbackSerializer.process_callback(
+            request, carrier_name
+        )
+
+        accept_header = request.headers.get("Accept", "")
+
+        if "text/html" in accept_header and frontend_url:
+            result_encoded = base64.b64encode(
+                json.dumps(result).encode("utf-8")
+            ).decode("utf-8")
+            return HttpResponseRedirect(f"{frontend_url}?oauth_result={result_encoded}")
+
+        if "text/html" in accept_header:
+            error_message = (
+                result["messages"][0]["message"]
+                if result["messages"]
+                else "An error occurred during authorization."
+            )
+            return render(
+                request._request,
+                "providers/oauth_callback.html",
+                dict(
+                    success=result["success"],
+                    error_message=error_message,
+                    result_json=json.dumps(result),
+                ),
+            )
+
+        return response.Response(result, status=status.HTTP_200_OK)
+
+
 urlpatterns = [
     urls.path(
         "connections",
@@ -173,4 +463,34 @@ urlpatterns = [
         CarrierConnectionDetail.as_view(),
         name="carrier-connection-details",
     ),
+    urls.path(
+        "connections/oauth/<str:carrier_name>/authorize",
+        ConnectionOauthAuthorize.as_view(),
+        name="connection-oauth-authorize",
+    ),
+    urls.path(
+        "connections/oauth/<str:carrier_name>/callback",
+        ConnectionOauthCallback.as_view(),
+        name="connection-oauth-callback",
+    ),
+    urls.path(
+        "connections/webhook/<str:pk>/events",
+        ConnectionWebhookEvent.as_view(),
+        name="connection-webhook-event",
+    ),
+    urls.path(
+        "connections/webhook/<str:pk>/register",
+        ConnectionWebhookRegister.as_view(),
+        name="connection-webhook-register",
+    ),
+    urls.path(
+        "connections/webhook/<str:pk>/deregister",
+        ConnectionWebhookDeregister.as_view(),
+        name="connection-webhook-deregister",
+    ),
+    urls.path(
+        "connections/webhook/<str:pk>/disconnect",
+        ConnectionWebhookDisconnect.as_view(),
+        name="connection-webhook-disconnect",
+    ),
 ]

karrio/server/serializers/abstract.py

@@ -1,17 +1,16 @@
 import yaml
 import pydoc
 import typing
-import logging
 from django.db import models
-from django.conf import empty, settings
+from django.conf import settings
 from django.db import transaction
-from rest_framework import serializers
 from django.forms.models import model_to_dict
 from drf_spectacular.types import OpenApiTypes
+from rest_framework import serializers, request
 
 import karrio.lib as lib
+from karrio.server.core.logging import logger
 
-logger = logging.getLogger(__name__)
 T = typing.TypeVar("T")
 
 
@@ -24,6 +23,9 @@ class Context(typing.NamedTuple):
         return getattr(self, item)
 
 
+RequestContext = typing.Union[Context, dict, request.Request]
+
+
 class DecoratedSerializer:
     def __init__(
         self,
@@ -157,7 +159,9 @@ def PaginatedResult(serializer_name: str, content_serializer: typing.Type[Serial
     )
 
 
-def owned_model_serializer(serializer: typing.Type[Serializer]):
+def owned_model_serializer(
+    serializer: typing.Type[typing.Union[Serializer, ModelSerializer]],
+):
     class MetaSerializer(serializer):  # type: ignore
         context: dict = {}
 
@@ -196,8 +200,15 @@ def owned_model_serializer(serializer: typing.Type[Serializer]):
                 instance = super().create(payload, context=self.__context)
                 link_org(instance, self.__context)  # Link to organization if supported
             except Exception as e:
-                logger.exception(e)
-                raise e
+                # Log exception with full traceback for debugging
+                meta = getattr(self.__class__, "Meta", None)
+                model_name = getattr(
+                    getattr(meta, "model", None), "__name__", "Unknown"
+                )
+                logger.exception(
+                    f"Failed to create {model_name} instance using {self.__class__.__name__}: {str(e)}"
+                )
+                raise
 
             return instance
 
@@ -210,18 +221,22 @@ def owned_model_serializer(serializer: typing.Type[Serializer]):
 
 
 def link_org(entity: ModelSerializer, context: Context):
-    if (
-        context.org is not None
-        and hasattr(entity, "org")
-        and hasattr(entity.org, "exists")
-        and not entity.org.exists()
-    ):
-        entity.link = entity.__class__.link.related.related_model.objects.create(
-            org=context.org, item=entity
-        )
-        entity.save(
-            update_fields=(["created_at"] if hasattr(entity, "created_at") else [])
-        )
+    from django.utils.functional import SimpleLazyObject
+
+    # Evaluate org from context (handles SimpleLazyObject)
+    org = (
+        context.org if not isinstance(context.org, SimpleLazyObject)
+        else (context.org if context.org else None)
+    )
+
+    # Check if entity can be linked to org
+    entity_org = getattr(entity, "org", None)
+    has_org_relation = entity_org is not None and hasattr(entity_org, "exists")
+    should_link = org is not None and has_org_relation and not entity_org.exists()
+
+    if should_link:
+        entity.link = entity.__class__.link.related.related_model.objects.create(org=org, item=entity)
+        entity.save(update_fields=(["created_at"] if hasattr(entity, "created_at") else []))
 
 
 def bulk_link_org(entities: typing.List[models.Model], context: Context):
@@ -409,6 +424,80 @@ def is_field_optional(model, field_name: str) -> bool:
     return False
 
 
+def deep_merge_remove_nulls(base: dict, updates: dict) -> dict:
+    """Deep merge two dictionaries, removing keys with null values from updates.
+
+    Args:
+        base: The base dictionary (existing data)
+        updates: The updates dictionary (new data with potential nulls to remove)
+
+    Returns:
+        Merged dictionary with null values removed
+
+    Examples:
+        >>> base = {"a": 1, "b": {"c": 2, "d": 3}}
+        >>> updates = {"b": {"c": null, "e": 4}}
+        >>> deep_merge_remove_nulls(base, updates)
+        {"a": 1, "b": {"d": 3, "e": 4}}  # c removed due to null
+    """
+    result = base.copy()
+
+    for key, value in updates.items():
+        if value is None:
+            # Explicit null means remove the key
+            result.pop(key, None)
+        elif isinstance(value, dict) and isinstance(result.get(key), dict):
+            # Both are dicts: recursively merge
+            result[key] = deep_merge_remove_nulls(result[key], value)
+        else:
+            # Overwrite with new value
+            result[key] = value
+
+    return result
+
+
+def process_nested_dictionaries_mutations(
+    keys: typing.List[str], payload: dict, entity
+) -> dict:
+    """Process nested dictionary mutations with deep merge and null removal.
+
+    This function is designed for complex nested JSON fields where you need:
+    - Deep merging of nested objects
+    - Removal of keys when explicit null is sent
+    - Preservation of unaffected nested keys
+
+    Use this for fields like shipping rule actions/conditions that have nested extensions.
+    For simple flat dictionaries, use process_dictionaries_mutations instead.
+
+    Args:
+        keys: List of field names to process
+        payload: Input data from mutation
+        entity: Existing entity instance
+
+    Returns:
+        Updated payload with deep merged values
+
+    Examples:
+        Existing: {"actions": {"select_service": {"carrier": "ups"}, "extensions": {"old": "data"}}}
+        Update: {"actions": {"extensions": {"new": "data"}}}
+        Result: {"actions": {"select_service": {"carrier": "ups"}, "extensions": {"old": "data", "new": "data"}}}
+    """
+    data = payload.copy()
+
+    for key in [k for k in keys if k in payload]:
+        existing_value = getattr(entity, key, None) or {}
+        new_value = payload.get(key)
+
+        if new_value is None:
+            # Explicit null means clear the entire field
+            data[key] = {}
+        else:
+            # Deep merge with null removal
+            data[key] = deep_merge_remove_nulls(existing_value, new_value)
+
+    return data
+
+
 def process_dictionaries_mutations(
     keys: typing.List[str], payload: dict, entity
 ) -> dict:
@@ -417,8 +506,10 @@ def process_dictionaries_mutations(
     """
     data = payload.copy()
 
-    for key in [k for k in keys if k in payload]:
-        value = lib.to_dict({**getattr(entity, key, {}), **payload.get(key, {})})
+    for key in [k for k in keys if k in payload and payload.get(k) is not None]:
+        value = lib.to_dict(
+            {**(getattr(entity, key, None) or {}), **(payload.get(key, None) or {})}
+        )
         data.update({key: value})
 
     return data

karrio/server/tracing/utils.py

@@ -1,12 +1,9 @@
-import logging
-
 import karrio.lib as lib
 import karrio.server.conf as conf
 import karrio.server.core.utils as utils
 import karrio.server.tracing.models as models
 import karrio.server.serializers as serializers
-
-logger = logging.getLogger(__name__)
+from karrio.server.core.logging import logger
 
 
 @utils.error_wrapper
@@ -66,9 +63,9 @@ def save_tracing_records(context, tracer: lib.Tracer = None, schema: str = None)
             if getattr(context, "org", None) is not None:
                 serializers.bulk_link_org(saved_records, context)
 
-            logger.info("successfully saved tracing records...")
+            logger.info("Tracing records saved successfully", record_count=len(saved_records))
         except Exception as e:
-            logger.error(e, exc_info=False)
+            logger.error("Failed to save tracing records", error=str(e))
 
     persist_records(schema=schema)
 
@@ -84,7 +81,7 @@ def bulk_save_tracing_records(tracer: lib.Tracer, context=None):
     records = []
 
     for record in tracer.records:
-        logger.debug([f"record: {record.key}", record.metadata])
+        logger.debug("Processing tracing record", record_key=record.key, metadata=record.metadata)
         records.append(
             models.TracingRecord(
                 key=record.key,
@@ -101,7 +98,7 @@ def bulk_save_tracing_records(tracer: lib.Tracer, context=None):
     if getattr(context, "org", None) is not None:
         serializers.bulk_link_org(saved_records, context)
 
-    logger.info("> tracing records saved...")
+    logger.info("Tracing records saved successfully", record_count=len(saved_records))
 
 
 def set_tracing_context(**kwargs):

karrio/server/user/models.py

@@ -74,45 +74,47 @@ class User(auth.AbstractUser):
         import karrio.server.conf as conf
         import karrio.server.iam.models as iam
         import karrio.server.core.middleware as middleware
+        from django.utils.functional import SimpleLazyObject
 
         ctx = middleware.SessionContext.get_current_request()
-        _permissions = []
 
-        if (
-            conf.settings.MULTI_ORGANIZATIONS
-            and ctx is not None
-            and hasattr(ctx, "org")
-            and ctx.org is not None
-        ):
-            org_user = ctx.org.organization_users.filter(user_id=self.pk)
-            if org_user.exists():
-                try:
-                    context_permission = iam.ContextPermission.objects.get(
-                        object_pk=org_user.first().pk,
-                        content_type=ContentType.objects.get_for_model(
-                            org_user.first()
-                        ),
-                    )
-                    _permissions = list(
-                        context_permission.groups.all().values_list("name", flat=True)
-                    )
-                except iam.ContextPermission.DoesNotExist:
-                    pass
-
-        if not any(_permissions):
-            _permissions = list(self.groups.all().values_list("name", flat=True))
-
-        if not any(_permissions) and self.is_superuser:
-            return list(Group.objects.all().values_list("name", flat=True))
-
-        if not any(_permissions) and self.is_staff:
-            return list(
-                Group.objects.exclude(
-                    name__in=["manage_system", "manage_team", "manage_org_owner"]
-                ).values_list("name", flat=True)
+        # Helper to evaluate org safely
+        def get_org():
+            return (
+                None if not all([
+                    conf.settings.MULTI_ORGANIZATIONS,
+                    ctx is not None,
+                    hasattr(ctx, "org"),
+                    ctx.org is not None,
+                ]) else (
+                    ctx.org if not isinstance(ctx.org, SimpleLazyObject)
+                    else (ctx.org if ctx.org else None)
+                )
             )
 
-        return _permissions
+        # Helper to get context permissions
+        def get_context_perms():
+            org = get_org()
+            org_user = org.organization_users.filter(user_id=self.pk).first() if org else None
+
+            try:
+                context_permission = iam.ContextPermission.objects.get(
+                    object_pk=org_user.pk,
+                    content_type=ContentType.objects.get_for_model(org_user),
+                ) if org_user else None
+
+                return list(context_permission.groups.all().values_list("name", flat=True)) if context_permission else []
+            except iam.ContextPermission.DoesNotExist:
+                return []
+
+        # Functional chain of permission resolution
+        _permissions = get_context_perms() or list(self.groups.all().values_list("name", flat=True))
+
+        return (
+            list(Group.objects.all().values_list("name", flat=True)) if self.is_superuser and not _permissions
+            else list(Group.objects.exclude(name__in=["manage_system", "manage_team", "manage_org_owner"]).values_list("name", flat=True)) if self.is_staff and not _permissions
+            else _permissions
+        )
 
 
 @core.register_model

karrio/server/user/serializers.py

@@ -32,6 +32,7 @@ class TokenSerializer(serializers.Serializer):
         if queyset.exists():
             return queyset.first()
 
+        # Handle multi-organization mode
         if org_id is not None and conf.settings.MULTI_ORGANIZATIONS:
             import karrio.server.orgs.models as orgs