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

karrio/server/providers/serializers/base.py

@@ -0,0 +1,538 @@
+import typing
+import django.db.transaction as transaction
+from rest_framework import status as http_status
+
+import karrio.lib as lib
+import karrio.references as references
+import karrio.server.openapi as openapi
+import karrio.server.core.utils as utils
+import karrio.server.serializers as serializers
+import karrio.server.core.dataunits as dataunits
+import karrio.server.core.exceptions as exceptions
+import karrio.server.providers.models as providers
+from karrio.server.core.serializers import CARRIERS, Message
+
+
+def generate_carrier_serializers() -> typing.Dict[str, serializers.Serializer]:
+
+    def _create_serializer(carrier_name: str) -> serializers.Serializer:
+        fields = dataunits.REFERENCE_MODELS["connection_fields"][carrier_name]
+        return type(
+            carrier_name,
+            (serializers.Serializer,),
+            {
+                key: serializers.field_to_serializer(field)
+                for key, field in fields.items()
+            },
+        )
+
+    return {
+        carrier_name: _create_serializer(carrier_name)
+        for carrier_name in dataunits.REFERENCE_MODELS["carriers"].keys()
+    }
+
+
+CONNECTION_SERIALIZERS = generate_carrier_serializers()
+
+
+@openapi.extend_schema_field(
+    openapi.PolymorphicProxySerializer(
+        component_name="ConnectionCredentialsField",
+        serializers=CONNECTION_SERIALIZERS.values(),
+        resource_type_field_name=None,
+    )
+)
+class ConnectionCredentialsField(serializers.DictField):
+    pass
+
+
+@serializers.owned_model_serializer
+class CarrierConfigModelSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = providers.CarrierConfig
+        exclude = ["created_at", "updated_at", "created_by"]
+        extra_kwargs = {field: {"read_only": True} for field in ["id"]}
+
+
+class CarrierConnectionData(serializers.Serializer):
+
+    carrier_name = serializers.ChoiceField(
+        choices=CARRIERS,
+        required=True,
+        help_text="A carrier connection type.",
+    )
+    carrier_id = serializers.CharField(
+        required=True,
+        help_text="A carrier connection friendly name.",
+    )
+    credentials = ConnectionCredentialsField(
+        required=True,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    active = serializers.BooleanField(
+        required=False,
+        default=True,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+
+
+class CarrierConnectionUpdateData(serializers.Serializer):
+    carrier_id = serializers.CharField(
+        required=False, help_text="A carrier connection friendly name."
+    )
+    credentials = serializers.PlainDictField(
+        required=False,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    active = serializers.BooleanField(
+        required=False,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+
+
+class CarrierConnection(serializers.Serializer):
+    id = serializers.CharField(
+        required=True,
+        help_text="A unique carrier connection identifier",
+    )
+    object_type = serializers.CharField(
+        default="carrier-connection",
+        help_text="Specifies the object type",
+    )
+    carrier_name = serializers.ChoiceField(
+        choices=CARRIERS,
+        required=True,
+        help_text="A carrier connection type.",
+    )
+    display_name = serializers.CharField(
+        required=False,
+        help_text="The carrier connection type verbose name.",
+    )
+    carrier_id = serializers.CharField(
+        required=True,
+        help_text="A carrier connection friendly name.",
+    )
+    credentials = ConnectionCredentialsField(
+        required=False,
+        help_text="Carrier connection credentials.",
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Carrier connection custom config.",
+    )
+    metadata = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="User metadata for the carrier.",
+    )
+    is_system = serializers.BooleanField(
+        required=True,
+        help_text="The carrier connection is provided by the system admin.",
+    )
+    active = serializers.BooleanField(
+        required=True,
+        help_text="The active flag indicates whether the carrier account is active or not.",
+    )
+    test_mode = serializers.BooleanField(
+        required=True,
+        help_text="The test flag indicates whether to use a carrier configured for test.",
+    )
+
+
+@serializers.owned_model_serializer
+class CarrierConnectionModelSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = providers.Carrier
+        exclude = ["created_at", "updated_at", "created_by"]
+
+    carrier_name = serializers.ChoiceField(
+        required=True, choices=CARRIERS, help_text="Indicates a carrier (type)"
+    )
+    capabilities = serializers.StringListField(
+        required=False,
+        allow_null=True,
+        help_text="""The carrier enabled capabilities.""",
+    )
+    config = serializers.PlainDictField(
+        required=False,
+        allow_null=True,
+        help_text="Carrier connection custom config.",
+    )
+
+    @transaction.atomic
+    @utils.error_wrapper
+    def create(
+        self,
+        validated_data: dict,
+        context: serializers.Context,
+        **kwargs,
+    ) -> providers.Carrier:
+        config = validated_data.pop("config", None)
+        carrier_name = validated_data.pop("carrier_name")
+        default_capabilities = references.get_carrier_capabilities(carrier_name)
+        capabilities = lib.identity(
+            validated_data.get("capabilities")
+            if any(validated_data.get("capabilities") or [])
+            else default_capabilities
+        )
+
+        validated_data.update(test_mode=context.test_mode)
+        validated_data.update(carrier_code=carrier_name)
+        validated_data.update(
+            capabilities=[_ for _ in capabilities if _ in default_capabilities]
+        )
+        validated_data.update(
+            credentials=CONNECTION_SERIALIZERS[carrier_name]
+            .map(data=validated_data["credentials"])
+            .data
+        )
+
+        instance = super().create(validated_data, context=context, **kwargs)
+
+        if config is not None:
+            CarrierConfigModelSerializer.map(
+                context=context,
+                data={"carrier": instance.pk, "config": config},
+            ).save()
+
+        return providers.Carrier.objects.get(pk=instance.pk)
+
+    @transaction.atomic
+    @utils.error_wrapper
+    def update(
+        self,
+        instance: providers.Carrier,
+        validated_data: dict,
+        **kwargs,
+    ) -> providers.Carrier:
+        if any(validated_data.get("capabilities") or []):
+            default_capabilities = references.get_carrier_capabilities(instance.ext)
+            capabilities = validated_data.get("capabilities")
+            instance.capabilities = [
+                _ for _ in capabilities if _ in default_capabilities
+            ]
+
+        if "credentials" in validated_data:
+            data = serializers.process_dictionaries_mutations(
+                ["credentials"],
+                validated_data,
+                instance,
+            )
+            validated_data.update(
+                credentials=CONNECTION_SERIALIZERS[instance.ext]
+                .map(data=data["credentials"])
+                .data
+            )
+
+        if "config" in validated_data:
+            data = serializers.process_dictionaries_mutations(
+                ["config"],
+                dict(config=validated_data.pop("config")),
+                instance,
+            )
+            lib.identity(
+                CarrierConfigModelSerializer.map(
+                    instance=instance.carrier_config,
+                    context=kwargs.get("context"),
+                    data={"carrier": instance.pk, **data},
+                )
+                .save()
+                .instance
+            )
+
+        return super().update(instance, validated_data, **kwargs)
+
+
+# =============================================================================
+# Webhook Management Serializers
+# =============================================================================
+
+
+class WebhookOperationResponse(serializers.Serializer):
+    """Response serializer for webhook operations."""
+
+    operation = serializers.CharField(help_text="The operation performed")
+    success = serializers.BooleanField(help_text="Whether the operation was successful")
+    carrier_name = serializers.CharField(help_text="The carrier name")
+    carrier_id = serializers.CharField(help_text="The carrier connection ID")
+    messages = Message(
+        required=False,
+        many=True,
+        help_text="Operation messages or errors",
+    )
+
+
+class WebhookRegisterData(serializers.Serializer):
+    """Request serializer for webhook registration."""
+
+    enabled_events = serializers.StringListField(
+        required=False,
+        default=["*"],
+        help_text="Events to subscribe to. Defaults to all events.",
+    )
+    description = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        help_text="Description for the webhook registration.",
+    )
+
+
+class WebhookRegisterSerializer(serializers.Serializer):
+    """Handles webhook registration with carriers. Returns webhook details on success."""
+
+    webhook_url = serializers.URLField(
+        required=True,
+        help_text="The URL to receive webhook events.",
+    )
+    description = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        help_text="Description for the webhook registration.",
+    )
+
+    @utils.error_wrapper
+    def update(self, connection: providers.Carrier, validated_data: dict, **kwargs):
+        import karrio.server.core.gateway as gateway
+
+        webhook_url = validated_data["webhook_url"]
+        description = validated_data.get(
+            "description", f"Karrio webhook for {connection.carrier_id}"
+        )
+
+        webhook_details, messages = gateway.Webhooks.register(
+            dict(url=webhook_url, description=description),
+            carrier=connection,
+            **kwargs,
+        )
+
+        if webhook_details is None:
+            raise exceptions.APIException(
+                detail=messages,
+                status_code=http_status.HTTP_424_FAILED_DEPENDENCY,
+            )
+
+        return webhook_details
+
+
+class WebhookDeregisterSerializer(serializers.Serializer):
+    """Handles webhook deregistration from carriers. Returns confirmation on success."""
+
+    webhook_id = serializers.CharField(
+        required=True,
+        help_text="The webhook ID to deregister.",
+    )
+
+    @utils.error_wrapper
+    def update(self, connection: providers.Carrier, validated_data: dict, **kwargs):
+        import karrio.server.core.gateway as gateway
+
+        confirmation, messages = gateway.Webhooks.unregister(
+            payload=dict(webhook_id=validated_data["webhook_id"]),
+            carrier=connection,
+        )
+
+        if not (confirmation and confirmation.success):
+            raise exceptions.APIException(
+                detail=messages,
+                status_code=http_status.HTTP_424_FAILED_DEPENDENCY,
+            )
+
+        return confirmation
+
+
+# =============================================================================
+# OAuth Callback Serializers
+# =============================================================================
+
+
+class OAuthAuthorizeData(serializers.Serializer):
+    """Request serializer for OAuth authorization."""
+
+    frontend_url = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        help_text="Frontend URL to redirect to after OAuth callback.",
+    )
+
+
+class OAuthCallbackData(serializers.Serializer):
+    """Request serializer for OAuth callback data."""
+
+    query = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Query parameters from the OAuth callback.",
+    )
+    body = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Body data from the OAuth callback.",
+    )
+    headers = serializers.PlainDictField(
+        required=False,
+        default={},
+        help_text="Headers from the OAuth callback.",
+    )
+    url = serializers.CharField(
+        required=False,
+        help_text="The full callback URL.",
+    )
+
+
+class OAuthCallbackSerializer(serializers.Serializer):
+    """Handles OAuth callback processing logic."""
+
+    @staticmethod
+    def process_callback(
+        request,
+        carrier_name: str,
+    ) -> dict:
+        """Process OAuth callback and return result dict."""
+        import json
+        import base64
+        import karrio.lib as lib
+        import karrio.server.core.gateway as gateway
+
+        payload = OAuthCallbackData.map(
+            data=dict(
+                query=request.query_params.dict(),
+                body=(
+                    request.data.dict()
+                    if hasattr(request.data, "dict")
+                    else dict(request.data or {})
+                ),
+                headers=dict(request.headers),
+                url=request.build_absolute_uri(),
+            )
+        ).data
+
+        [output, messages] = gateway.Hooks.on_oauth_callback(
+            payload=payload,
+            carrier_name=carrier_name,
+            test_mode=request.test_mode,
+            context=request,
+        )
+
+        result = dict(
+            type="oauth_callback",
+            success=output is not None,
+            carrier_name=carrier_name,
+            credentials=lib.to_dict(output) if output else None,
+            messages=lib.to_dict(messages),
+            state=request.query_params.get("state"),
+        )
+
+        frontend_url = None
+        state = request.query_params.get("state")
+        if state:
+            try:
+                state_data = json.loads(base64.b64decode(state).decode("utf-8"))
+                frontend_url = state_data.get("frontend_url")
+            except Exception:
+                pass
+
+        return result, frontend_url
+
+
+# =============================================================================
+# Webhook Event Serializers
+# =============================================================================
+
+
+class WebhookEventSerializer(serializers.Serializer):
+    """Handles webhook event processing logic."""
+
+    @staticmethod
+    def process_event(request, pk: str) -> tuple:
+        """
+        Process webhook event and return response data and status code.
+
+        Returns:
+            tuple: (response_data, http_status_code)
+        """
+        import django.db.models as django
+        import karrio.lib as lib
+        import karrio.server.core.gateway as gateway
+
+        try:
+            connection = providers.Carrier.objects.get(pk=pk)
+        except providers.Carrier.DoesNotExist:
+            return (
+                dict(
+                    operation="Webhook event",
+                    success=False,
+                    messages=[{"message": f"Connection not found: {pk}"}],
+                ),
+                http_status.HTTP_404_NOT_FOUND,
+            )
+
+        event, messages = gateway.Hooks.on_webhook_event(
+            payload=dict(
+                url=request.build_absolute_uri(),
+                body=request.data,
+                query=dict(request.query_params),
+                headers=dict(request.headers),
+            ),
+            carrier=connection,
+        )
+
+        if event and event.tracking:
+            import karrio.server.manager.models as manager_models
+            import karrio.server.manager.serializers.tracking as tracking_serializers
+
+            tracker = manager_models.Tracking.objects.filter(
+                django.Q(tracking_number=event.tracking.tracking_number)
+                | django.Q(tracking_carrier=connection)
+            ).first()
+
+            if tracker:
+                tracking_serializers.update_tracker(
+                    tracker, lib.to_dict(event.tracking)
+                )
+
+        return (
+            dict(
+                operation="Webhook event",
+                success=len(messages) == 0,
+                carrier_name=connection.carrier_name,
+                carrier_id=connection.carrier_id,
+                messages=lib.to_dict(messages),
+            ),
+            http_status.HTTP_200_OK,
+        )

karrio/server/providers/signals.py

@@ -0,0 +1,25 @@
+from django.db.models import signals
+
+import karrio.references as ref
+import karrio.server.core.utils as utils
+from karrio.server.core.logging import logger
+import karrio.server.providers.models as models
+
+
+def register_signals():
+    signals.post_save.connect(carrier_changed, sender=models.Carrier)
+
+    logger.info("Karrio providers signals registered")
+
+
+@utils.disable_for_loaddata
+def carrier_changed(
+    sender, instance, created, raw, using, update_fields, *args, **kwargs
+):
+    """Setup default capabilities when carrier are created."""
+    if not created:
+        return
+
+    if len(instance.capabilities or []) == 0:
+        instance.capabilities = ref.get_carrier_capabilities(instance.carrier_code)
+        instance.save()

karrio/server/providers/templates/providers/oauth_callback.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>OAuth Callback</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: #f5f5f5;
+        }
+        .container {
+            text-align: center;
+            padding: 40px;
+            background: white;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+            max-width: 400px;
+        }
+        .success { color: #16a34a; }
+        .error { color: #dc2626; }
+        .icon {
+            font-size: 48px;
+            margin-bottom: 16px;
+        }
+        h2 { margin-bottom: 10px; }
+        p { color: #666; margin-bottom: 20px; }
+        .close-hint {
+            font-size: 12px;
+            color: #999;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="icon">{% if success %}✓{% else %}✗{% endif %}</div>
+        <h2 class="{% if success %}success{% else %}error{% endif %}">
+            {% if success %}Authorization Successful{% else %}Authorization Failed{% endif %}
+        </h2>
+        <p>{% if success %}You can close this window and return to the application.{% else %}{{ error_message }}{% endif %}</p>
+        <p class="close-hint">This window will close automatically...</p>
+    </div>
+    <script>
+        (async function() {
+            var result = {{ result_json|safe }};
+
+            /**
+             * Encrypts data using AES-GCM with Web Crypto API.
+             * Returns an object containing the encrypted data, IV, and key (all base64 encoded).
+             */
+            async function encryptData(data) {
+                // Generate a random 256-bit key
+                var key = await crypto.subtle.generateKey(
+                    { name: "AES-GCM", length: 256 },
+                    true, // extractable - needed to export the key
+                    ["encrypt", "decrypt"]
+                );
+
+                // Generate a random 96-bit IV (recommended for AES-GCM)
+                var iv = crypto.getRandomValues(new Uint8Array(12));
+
+                // Encode the data as UTF-8
+                var encoder = new TextEncoder();
+                var encodedData = encoder.encode(data);
+
+                // Encrypt the data
+                var encryptedBuffer = await crypto.subtle.encrypt(
+                    { name: "AES-GCM", iv: iv },
+                    key,
+                    encodedData
+                );
+
+                // Export the key for storage
+                var exportedKey = await crypto.subtle.exportKey("raw", key);
+
+                // Convert to base64 for storage
+                var ciphertext = btoa(String.fromCharCode.apply(null, new Uint8Array(encryptedBuffer)));
+                var ivBase64 = btoa(String.fromCharCode.apply(null, iv));
+                var keyBase64 = btoa(String.fromCharCode.apply(null, new Uint8Array(exportedKey)));
+
+                return { ciphertext: ciphertext, iv: ivBase64, key: keyBase64 };
+            }
+
+            // Store encrypted result in localStorage for the opener to read
+            // Using localStorage (not sessionStorage) because popup windows have
+            // separate sessionStorage contexts from their opener window.
+            // Data is encrypted with AES-GCM for security.
+            try {
+                var encrypted = await encryptData(JSON.stringify(result));
+                localStorage.setItem('karrio_oauth_result', JSON.stringify(encrypted));
+            } catch (e) {
+                console.error('Failed to encrypt/store OAuth result:', e);
+            }
+
+            // Try to close the window after a short delay
+            setTimeout(function() {
+                window.close();
+            }, 2000);
+        })();
+    </script>
+</body>
+</html>

karrio/server/providers/tests/__init__.py

@@ -0,0 +1,5 @@
+import logging
+
+logging.disable(logging.CRITICAL)
+
+from karrio.server.providers.tests.test_connections import *