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

karrio/server/core/utils.py

@@ -1,9 +1,7 @@
 import sys
 import typing
 import inspect
-import logging
 import functools
-from string import Template
 from concurrent import futures
 from datetime import timedelta, datetime
 from typing import TypeVar, Union, Callable, Any, List, Optional
@@ -13,13 +11,13 @@ from django.utils.translation import gettext_lazy as _
 import django_email_verification.confirm as confirm
 import rest_framework_simplejwt.tokens as jwt
 import rest_framework.status as status
+from karrio.server.core.logging import logger
 
 import karrio.lib as lib
 from karrio.core.utils import DP, DF
 from karrio.server.core import datatypes, serializers, exceptions
 
 T = TypeVar("T")
-logger = logging.getLogger(__name__)
 
 
 def identity(value: Union[Any, Callable]) -> Any:
@@ -30,6 +28,103 @@ def identity(value: Union[Any, Callable]) -> Any:
     return value() if callable(value) else value
 
 
+def execute_gateway_operation(
+    operation_name: str,
+    callable: Callable[[], T],
+    carrier: Any = None,
+    context: Any = None,
+) -> T:
+    """Execute a gateway operation with telemetry instrumentation.
+
+    This function wraps SDK gateway calls (rates, shipments, tracking, etc.)
+    with telemetry spans for observability when Sentry is configured.
+
+    Args:
+        operation_name: Name of the operation (e.g., "rates_fetch", "shipment_create")
+        callable: The callable that performs the SDK operation
+        carrier: Optional carrier instance for context
+        context: Optional request context for accessing the tracer
+
+    Returns:
+        The result of the callable
+
+    Example:
+        result = execute_gateway_operation(
+            "rates_fetch",
+            lambda: karrio.Rating.fetch(request).from_(carrier.gateway).parse(),
+            carrier=carrier,
+            context=context,
+        )
+    """
+    tracer = _get_tracer_from_context(context)
+
+    # Build span attributes
+    attributes = {}
+    if carrier:
+        attributes["carrier_name"] = getattr(carrier, "carrier_code", None)
+        attributes["carrier_id"] = getattr(carrier, "carrier_id", None)
+        attributes["test_mode"] = getattr(carrier, "test_mode", None)
+
+    span_name = f"karrio_{operation_name}"
+
+    with tracer.start_span(span_name, attributes=attributes) as span:
+        try:
+            result = callable()
+            span.set_status("ok")
+
+            # Record success metric
+            tracer.record_metric(
+                f"karrio_{operation_name}_success",
+                1,
+                tags={
+                    "carrier": attributes.get("carrier_name", "unknown"),
+                    "test_mode": str(attributes.get("test_mode", False)).lower(),
+                },
+            )
+
+            return result
+
+        except Exception as e:
+            span.set_status("error", str(e))
+            span.record_exception(e)
+
+            # Record failure metric
+            tracer.record_metric(
+                f"karrio_{operation_name}_error",
+                1,
+                tags={
+                    "carrier": attributes.get("carrier_name", "unknown"),
+                    "error_type": type(e).__name__,
+                },
+            )
+
+            raise
+
+
+def _get_tracer_from_context(context: Any) -> lib.Tracer:
+    """Get the tracer from request context or return a default one."""
+    if context is None:
+        # Try to get from current request via middleware
+        try:
+            from karrio.server.core.middleware import SessionContext
+
+            request = SessionContext.get_current_request()
+            if request and hasattr(request, "tracer"):
+                return request.tracer
+        except Exception:
+            pass
+
+    # Try to get from context object
+    if hasattr(context, "tracer"):
+        return context.tracer
+
+    if hasattr(context, "request") and hasattr(context.request, "tracer"):
+        return context.request.tracer
+
+    # Return a default tracer (with NoOpTelemetry)
+    return lib.Tracer()
+
+
 def failsafe(callable: Callable[[], T], warning: str = None) -> T:
     """This higher order function wraps a callable in a try..except
     scope to capture any exception raised.
@@ -40,7 +135,7 @@ def failsafe(callable: Callable[[], T], warning: str = None) -> T:
         return callable()
     except Exception as e:
         if warning:
-            logger.warning(Template(warning).substitute(error=e))
+            logger.warning(warning, error=str(e))
         return None
 
 
@@ -78,6 +173,85 @@ def async_wrapper(func):
     return wrapper
 
 
+def with_telemetry(operation_name: str = None):
+    """Decorator that adds telemetry instrumentation to gateway methods.
+
+    This decorator wraps gateway methods with telemetry spans for observability.
+    When Sentry is configured, it creates spans for each operation with relevant
+    context (carrier info, operation type, etc.).
+
+    Args:
+        operation_name: Optional custom operation name. If not provided,
+                       the function name is used.
+
+    Usage:
+        class Shipments:
+            @staticmethod
+            @with_telemetry("shipment_create")
+            def create(payload: dict, carrier: Carrier = None, **kwargs):
+                ...
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            op_name = operation_name or func.__name__
+
+            # Extract carrier and context from kwargs if available
+            carrier = kwargs.get("carrier")
+            context = kwargs.get("context")
+
+            # Get tracer from context
+            tracer = _get_tracer_from_context(context)
+
+            # Build span attributes
+            attributes = {"operation": op_name}
+            if carrier:
+                attributes["carrier_name"] = getattr(carrier, "carrier_code", None)
+                attributes["carrier_id"] = getattr(carrier, "carrier_id", None)
+                attributes["test_mode"] = getattr(carrier, "test_mode", None)
+
+            span_name = f"karrio_{op_name}"
+
+            with tracer.start_span(span_name, attributes=attributes) as span:
+                try:
+                    result = func(*args, **kwargs)
+                    span.set_status("ok")
+
+                    # Record success metric
+                    tracer.record_metric(
+                        f"karrio_{op_name}_success",
+                        1,
+                        tags={
+                            "carrier": attributes.get("carrier_name", "unknown")
+                            or "unknown",
+                        },
+                    )
+
+                    return result
+
+                except Exception as e:
+                    span.set_status("error", str(e))
+                    span.record_exception(e)
+
+                    # Record error metric
+                    tracer.record_metric(
+                        f"karrio_{op_name}_error",
+                        1,
+                        tags={
+                            "carrier": attributes.get("carrier_name", "unknown")
+                            or "unknown",
+                            "error_type": type(e).__name__,
+                        },
+                    )
+
+                    raise
+
+        return wrapper
+
+    return decorator
+
+
 def tenant_aware(func):
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -200,6 +374,37 @@ def upper(value_str: Optional[str]) -> Optional[str]:
     return value_str.upper().replace("_", " ")
 
 
+def batch_get_constance_values(keys: List[str]) -> dict:
+    """
+    Batch fetch multiple configuration values from Django Constance.
+
+    This function uses Constance's mget() method to fetch all requested
+    configuration keys in a single database query, avoiding N+1 query issues.
+
+    Args:
+        keys: List of configuration key names to fetch
+
+    Returns:
+        Dictionary mapping configuration keys to their values
+
+    Example:
+        >>> flags = batch_get_constance_values(['AUDIT_LOGGING', 'ALLOW_SIGNUP'])
+        >>> print(flags['AUDIT_LOGGING'])
+        True
+    """
+    from constance import config
+
+    try:
+        # Use mget to fetch all config values in a single query
+        # mget returns a generator of (key, value) tuples
+        return dict(config._backend.mget(keys))
+    except Exception as e:
+        logger.warning(
+            "Failed to batch fetch constance values, returning empty dict", error=str(e)
+        )
+        return {}
+
+
 def compute_tracking_status(
     details: Optional[datatypes.Tracking] = None,
 ) -> serializers.TrackerStatus:
@@ -222,7 +427,7 @@ def compute_tracking_status(
 
 
 def is_sdk_message(
-    message: Optional[Union[datatypes.Message, List[datatypes.Message]]]
+    message: Optional[Union[datatypes.Message, List[datatypes.Message]]],
 ) -> bool:
     msg = next(iter(message), None) if isinstance(message, list) else message
 
@@ -236,14 +441,15 @@ def filter_rate_carrier_compatible_gateways(
     This function filters the carriers based on the capability to "rating"
     and if no explicit carrier list is provided, it will filter out any
     carrier that does not support the shipper's country code.
+    Carriers with no account_country_code set are always included.
     """
     _gateways = [
         carrier.gateway
         for carrier in carriers
         if (
-            # If no carrier list is provided, and gateway has "rating" capability.
+            # If explicit carrier list is provided and gateway has "rating" capability.
             ("rating" in carrier.gateway.capabilities and len(carrier_ids) > 0)
-            # If a carrier list is provided, and gateway is in the list.
+            # If no carrier list is provided, and gateway is in the list.
             or (
                 # the gateway has "rating" capability.
                 "rating" in carrier.gateway.capabilities
@@ -252,9 +458,10 @@ def filter_rate_carrier_compatible_gateways(
                 # and the shipper country code is provided.
                 and shipper_country_code is not None
                 and (
-                    carrier.gateway.settings.account_country_code
+                    # Carriers with no account_country_code work across countries
+                    not carrier.gateway.settings.account_country_code
+                    or carrier.gateway.settings.account_country_code
                     == shipper_country_code
-                    or carrier.gateway.settings.account_country_code is None
                 )
             )
         )
@@ -306,6 +513,259 @@ class ConfirmationToken(jwt.Token):
         return token
 
 
+class ResourceAccessToken(jwt.Token):
+    """JWT token for limited resource access (documents, exports, etc.)."""
+
+    token_type = "resource_access"
+    lifetime = timedelta(minutes=5)
+
+    @classmethod
+    def for_resource(
+        cls,
+        user,
+        resource_type: str,
+        resource_ids: List[str],
+        access: List[str],
+        format: Optional[str] = None,
+        org_id: Optional[str] = None,
+        test_mode: Optional[bool] = None,
+        expires_in: Optional[int] = None,
+    ) -> "ResourceAccessToken":
+        """Generate a resource access token.
+
+        Args:
+            user: The authenticated user
+            resource_type: Type of resource (shipment, manifest, template, document)
+            resource_ids: List of resource IDs to grant access to
+            access: List of access permissions (label, invoice, manifest, render, etc.)
+            format: Document format (pdf, png, zpl)
+            org_id: Organization ID for multi-tenant environments
+            test_mode: Whether this is test mode
+            expires_in: Custom expiration time in seconds
+
+        Returns:
+            ResourceAccessToken instance
+        """
+        token = cls()
+        token["user_id"] = user.id if hasattr(user, "id") else user
+        token["resource_type"] = resource_type
+        token["resource_ids"] = resource_ids
+        token["access"] = access
+
+        if format:
+            token["format"] = format
+        if org_id:
+            token["org_id"] = org_id
+        if test_mode is not None:
+            token["test_mode"] = test_mode
+        if expires_in:
+            token.set_exp(lifetime=timedelta(seconds=expires_in))
+
+        return token
+
+    @classmethod
+    def decode(cls, token_string: str) -> dict:
+        """Decode and validate a resource access token.
+
+        Args:
+            token_string: The JWT token string
+
+        Returns:
+            Dictionary with token claims
+
+        Raises:
+            rest_framework_simplejwt.exceptions.TokenError: If token is invalid
+        """
+        token = cls(token_string)
+        return {
+            "user_id": token.get("user_id"),
+            "resource_type": token.get("resource_type"),
+            "resource_ids": token.get("resource_ids", []),
+            "access": token.get("access", []),
+            "format": token.get("format"),
+            "org_id": token.get("org_id"),
+            "test_mode": token.get("test_mode"),
+        }
+
+    @classmethod
+    def validate_access(
+        cls,
+        token_string: str,
+        resource_type: str,
+        resource_id: str,
+        access: str,
+    ) -> dict:
+        """Validate token grants access to specific resource and action.
+
+        Args:
+            token_string: The JWT token string
+            resource_type: Expected resource type
+            resource_id: Resource ID to check access for
+            access: Access permission to check
+
+        Returns:
+            Token claims if valid
+
+        Raises:
+            rest_framework_simplejwt.exceptions.TokenError: If token is invalid
+            PermissionError: If access is not granted
+        """
+        claims = cls.decode(token_string)
+
+        if claims["resource_type"] != resource_type:
+            raise PermissionError(f"Token not valid for resource type: {resource_type}")
+
+        if resource_id not in claims["resource_ids"]:
+            raise PermissionError(f"Token not valid for resource: {resource_id}")
+
+        if access not in claims["access"]:
+            raise PermissionError(f"Token does not grant access: {access}")
+
+        return claims
+
+    @classmethod
+    def validate_batch_access(
+        cls,
+        token_string: str,
+        resource_type: str,
+        resource_ids: List[str],
+        access: str,
+    ) -> dict:
+        """Validate token grants access to multiple resources.
+
+        Args:
+            token_string: The JWT token string
+            resource_type: Expected resource type
+            resource_ids: List of resource IDs to check access for
+            access: Access permission to check
+
+        Returns:
+            Token claims if valid
+
+        Raises:
+            rest_framework_simplejwt.exceptions.TokenError: If token is invalid
+            PermissionError: If access is not granted
+        """
+        claims = cls.decode(token_string)
+
+        if claims["resource_type"] != resource_type:
+            raise PermissionError(f"Token not valid for resource type: {resource_type}")
+
+        if access not in claims["access"]:
+            raise PermissionError(f"Token does not grant access: {access}")
+
+        token_ids = set(claims["resource_ids"])
+        request_ids = set(resource_ids)
+        if not request_ids.issubset(token_ids):
+            missing = request_ids - token_ids
+            raise PermissionError(
+                f"Token does not grant access to resources: {', '.join(missing)}"
+            )
+
+        return claims
+
+
+def validate_resource_token(
+    request,
+    resource_type: str,
+    resource_ids: List[str],
+    access: str,
+):
+    """Validate resource access token, skipping if user is already authenticated.
+
+    If the request has an authenticated user (via API token, JWT, etc.),
+    the resource token check is skipped. Otherwise, it validates the
+    resource access token from the query parameter.
+
+    Note: For this to work with non-DRF views, use the `APITokenAuthMixin`
+    on your view class to run DRF authentication before this function is called.
+
+    Args:
+        request: The HTTP request object
+        resource_type: Expected resource type (shipment, manifest, template, etc.)
+        resource_ids: List of resource IDs to validate access for
+        access: Required access permission (label, invoice, manifest, render, etc.)
+
+    Returns:
+        HttpResponseForbidden if validation fails, None if valid
+
+    Example:
+        error = validate_resource_token(request, "shipment", [pk], "label")
+        if error:
+            return error
+    """
+    from django.http import HttpResponseForbidden
+    from django.contrib.auth.models import AnonymousUser
+
+    # Skip resource token check if user is already authenticated
+    if hasattr(request, "user") and request.user and not isinstance(request.user, AnonymousUser):
+        if request.user.is_authenticated:
+            return None
+
+    # Fall back to resource access token validation
+    token = request.GET.get("token")
+
+    if not token:
+        return HttpResponseForbidden(
+            "Access token required. Use /api/tokens to generate one, or provide API token in Authorization header."
+        )
+
+    try:
+        ResourceAccessToken.validate_batch_access(
+            token_string=token,
+            resource_type=resource_type,
+            resource_ids=resource_ids,
+            access=access,
+        )
+        return None
+    except PermissionError as e:
+        return HttpResponseForbidden(
+            "You do not have permission to access these resources."
+        )
+    except Exception as e:
+        logger.warning("Invalid resource access token: %s", str(e))
+        return HttpResponseForbidden("Invalid or expired token.")
+
+
+def require_resource_token(
+    resource_type: str,
+    access: str,
+    get_resource_ids: Callable[..., List[str]],
+):
+    """Decorator for views requiring resource access token validation.
+
+    Args:
+        resource_type: Expected resource type (shipment, manifest, template, etc.)
+        access: Required access permission (label, invoice, manifest, render, etc.)
+        get_resource_ids: Callable that extracts resource IDs from request and view kwargs.
+                         Receives (request, **kwargs), returns list of resource IDs.
+
+    Example:
+        @require_resource_token(
+            resource_type="document",
+            access="batch_labels",
+            get_resource_ids=lambda req, **kw: req.GET.get("shipments", "").split(","),
+        )
+        def get(self, request, **kwargs):
+            ...
+    """
+
+    def decorator(method):
+        @functools.wraps(method)
+        def wrapper(self, request, *args, **kwargs):
+            resource_ids = get_resource_ids(request, **kwargs)
+            error = validate_resource_token(
+                request, resource_type, resource_ids, access
+            )
+            if error:
+                return error
+            return method(self, request, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 def app_tracking_query_params(url: str, carrier) -> str:
     hub_flag = f"&hub={carrier.carrier_name}" if carrier.gateway.is_hub else ""
 
@@ -336,6 +796,24 @@ def get_carrier_tracking_link(carrier, tracking_number: str):
     return tracking_url.format(tracking_number) if tracking_url is not None else None
 
 
+def _ensure_picked_up_status(events: typing.List[dict]) -> typing.List[dict]:
+    """Transform the chronologically first in_transit event to picked_up if none exists."""
+    if not events or any(e.get("status") == "picked_up" for e in events):
+        return events
+
+    # Events are sorted desc, so first in_transit chronologically is last in list
+    first_idx = next(
+        (i for i in range(len(events) - 1, -1, -1) if events[i].get("status") == "in_transit"),
+        None,
+    )
+
+    return (
+        [{**e, "status": "picked_up"} if i == first_idx else e for i, e in enumerate(events)]
+        if first_idx is not None
+        else events
+    )
+
+
 def process_events(
     response_events: typing.List[datatypes.TrackingEvent],
     current_events: typing.List[dict],
@@ -346,33 +824,173 @@ def process_events(
         return current_events
 
     new_events = lib.to_dict(response_events)
+
+    # If no current events, return new events as-is (already sorted by SDK)
     if not any(current_events):
-        return sorted(
-            new_events,
-            key=lambda e: f"{e.get('date', '')} {e.get('time', '')}",
-            reverse=True,
+        return new_events
+
+    # Merge events: add only new non-duplicate events to existing ones
+    current_hashes = {lib.to_json(event) for event in current_events}
+    unique_new_events = [
+        event for event in new_events if lib.to_json(event) not in current_hashes
+    ]
+
+    # If no new unique events, return current events unchanged
+    if not any(unique_new_events):
+        return current_events
+
+    # When merging, we need to re-sort because new events may have timestamps
+    # that fall between existing events. We must parse datetimes properly
+    # (not use string comparison) to handle 12-hour AM/PM format correctly.
+    def try_parse_datetime(value: str, fmt: str) -> typing.Optional[datetime]:
+        """Safely attempt to parse a datetime string with a given format."""
+        return failsafe(lambda: datetime.strptime(value, fmt))
+
+    def parse_date(event: dict) -> typing.Optional[datetime]:
+        """Parse date from event using multiple format attempts."""
+        date_str = event.get("date", "")
+        date_formats = ["%Y-%m-%d", "%m/%d/%Y", "%-m/%d/%Y"]
+        return (
+            functools.reduce(
+                lambda acc, fmt: acc or try_parse_datetime(date_str, fmt),
+                date_formats,
+                None,
+            )
+            if date_str
+            else None
+        )
+
+    def parse_time(event: dict) -> typing.Optional[datetime.time]:
+        """Parse time from event using multiple format attempts."""
+        time_str = event.get("time", "")
+        time_formats = ["%I:%M %p", "%H:%M:%S", "%H:%M", "%I:%M"]
+        parsed = (
+            functools.reduce(
+                lambda acc, fmt: acc or try_parse_datetime(time_str, fmt),
+                time_formats,
+                None,
+            )
+            if time_str
+            else None
+        )
+        return parsed.time() if parsed else None
+
+    def parse_event_datetime(event: dict) -> typing.Optional[datetime]:
+        """Parse complete datetime from event date and time."""
+        parsed_date = parse_date(event)
+        parsed_time = parse_time(event) if parsed_date else None
+        return (
+            datetime.combine(parsed_date.date(), parsed_time)
+            if parsed_date and parsed_time
+            else parsed_date
+        )
+
+    def create_sort_key(event: dict) -> tuple:
+        """Create sort key: dated events first (by datetime desc), undated last (by original order)."""
+        dt = parse_event_datetime(event)
+        return (0 if dt else 1, dt if dt else datetime.min)
+
+    # Merge and sort all events
+    merged_events = current_events + unique_new_events
+    sorted_events = sorted(merged_events, key=create_sort_key, reverse=True)
+
+    # Transform first in_transit to picked_up if no picked_up exists
+    # This provides a consistent pickup milestone across all carriers
+    return _ensure_picked_up_status(sorted_events)
+
+
+def _get_carrier_for_service(service: str, context=None) -> typing.Optional[str]:
+    """Resolve carrier name from service code using karrio references."""
+    import karrio.server.core.dataunits as dataunits
+
+    services_map = dataunits.contextual_reference(context).get("services", {})
+
+    return next(
+        (
+            carrier_name
+            for carrier_name, services in services_map.items()
+            if service in services
+        ),
+        None,
+    )
+
+
+def load_and_apply_shipping_method(
+    validated_data: dict,
+    shipping_method_id: str,
+    context: typing.Any,
+) -> dict:
+    """
+    Load a shipping method and apply its configuration to shipment data.
+
+    This function loads a ShippingMethod by ID and applies its configuration
+    to the validated_data dictionary using the shared apply_shipping_method_to_data
+    helper from the shipping module.
+
+    Args:
+        validated_data: The shipment data dictionary
+        shipping_method_id: The ID of the shipping method to load
+        context: The request context for access control
+
+    Returns:
+        dict: Modified validated_data with shipping method configuration applied
+
+    Raises:
+        APIException: If shipping method not found, inactive, or module not installed
+    """
+    try:
+        from karrio.server.shipping.models import ShippingMethod
+        from karrio.server.shipping.serializers import apply_shipping_method_to_data
+    except ImportError:
+        raise exceptions.APIException(
+            "Shipping methods module is not installed.",
+            code="module_not_installed",
+            status_code=status.HTTP_400_BAD_REQUEST,
         )
 
-    # Create hash for comparison using lib.to_json
-    event_hashes = {lib.to_json(event): event for event in current_events}
+    # Load the shipping method with access control
+    try:
+        method = ShippingMethod.access_by(context).get(
+            id=shipping_method_id,
+            is_active=True,
+        )
+    except ShippingMethod.DoesNotExist:
+        raise exceptions.APIException(
+            f"Shipping method '{shipping_method_id}' not found or inactive.",
+            code="shipping_method_not_found",
+            status_code=status.HTTP_404_NOT_FOUND,
+        )
 
-    for event in new_events:
-        event_hash = lib.to_json(event)
-        if event_hash not in event_hashes:
-            event_hashes[event_hash] = event
+    # Apply shipping method configuration using shared helper
+    result_data = apply_shipping_method_to_data(validated_data, method, context)
 
-    # Sort events by date and time in descending order (latest first)
-    return sorted(
-        event_hashes.values(),
-        key=lambda e: f"{e.get('date', '')} {e.get('time', '')}",
-        reverse=True,
+    logger.info(
+        "Applied shipping method to shipment",
+        shipping_method_id=method.id,
+        shipping_method_name=method.name,
+        carrier_service=method.carrier_service,
     )
 
+    return result_data
+
 
 def apply_rate_selection(payload: typing.Union[dict, typing.Any], **kwargs):
+    """
+    Select the appropriate rate based on the following priority hierarchy:
+
+    1. selected_rate (already provided) - highest priority
+    2. rate_id or service - try to find matching rate
+    3. has_alternative_services fallback - try carrier-based fallback
+    4. apply_shipping_rules - FALLBACK when no rate found from above
+
+    Shipping rules act as a fallback when:
+    - No service/rate_id provided, OR
+    - service/rate_id provided but no matching rate found
+    """
     data = kwargs.get("data") or kwargs
     get = lambda key, default=None: lib.identity(
-        payload.get(key, data.get(key, default)) if isinstance(payload, dict)
+        payload.get(key, data.get(key, default))
+        if isinstance(payload, dict)
         else getattr(payload, key, data.get(key, default))
     )
 
@@ -393,14 +1011,47 @@ def apply_rate_selection(payload: typing.Union[dict, typing.Any], **kwargs):
 
     # Select by id or service if provided
     if rate_id or service:
-        kwargs.update(selected_rate=next(
-            (
-                rate for rate in rates
-                if (rate_id and rate.get("id") == rate_id)
-                or (service and rate.get("service") == service)
-            ),
-            None,
-        ))
+        kwargs.update(
+            selected_rate=next(
+                (
+                    rate
+                    for rate in rates
+                    if (rate_id and rate.get("id") == rate_id)
+                    or (service and rate.get("service") == service)
+                ),
+                None,
+            )
+        )
+
+        # has_alternative_services fallback when no exact match found
+        has_alternative_services = options.get("has_alternative_services", False)
+
+        if kwargs.get("selected_rate") is None and has_alternative_services and service:
+            carrier_name = _get_carrier_for_service(service, ctx)
+            fallback_rate = lib.identity(
+                next(
+                    (r for r in rates if r.get("carrier_name") == carrier_name),
+                    None,
+                )
+                if carrier_name
+                else None
+            )
+
+            kwargs.update(
+                selected_rate=lib.identity(
+                    {
+                        **fallback_rate,
+                        "service": service,
+                        "meta": {
+                            **(fallback_rate.get("meta") or {}),
+                            "has_alternative_services": True,
+                        },
+                    }
+                    if fallback_rate
+                    else None
+                )
+            )
+
         return kwargs
 
     # Apply shipping rules if enabled and no selected rate is provided
@@ -411,9 +1062,7 @@ def apply_rate_selection(payload: typing.Union[dict, typing.Any], **kwargs):
 
         # Get active shipping rules
         active_rules = list(
-            automation_models.ShippingRule
-            .access_by(ctx)
-            .filter(is_active=True)
+            automation_models.ShippingRule.access_by(ctx).filter(is_active=True)
         )
 
         # Always run rule evaluation for activity tracking
@@ -421,6 +1070,7 @@ def apply_rate_selection(payload: typing.Union[dict, typing.Any], **kwargs):
             _, rule_selected_rate, rule_activity = engine.process_shipping_rules(
                 shipment=payload,
                 rules=active_rules,
+                context=ctx,
             )
 
             kwargs.update(
@@ -462,8 +1112,8 @@ def require_selected_rate(func):
                     "meta": {
                         **(result.meta or {}),
                         **({"rule_activity": kwargs.get("rule_activity")}),
-                    }
-                }
+                    },
+                },
             )
 
         if hasattr(result, "save") and kwargs.get("rule_activity"):