python-sendparcel 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

sendparcel/flow.py

@@ -1,19 +1,36 @@
 """Shipment flow orchestrator."""
 
+from __future__ import annotations
+
+from typing import Any
+
 import httpx
 
 from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import (
     CommunicationError,
-    InvalidTransitionError,
+    ProviderCapabilityError,
     SendParcelException,
 )
-from sendparcel.fsm import (
-    STATUS_TO_CALLBACK,
-    create_shipment_machine,
+from sendparcel.fsm import transition_shipment
+from sendparcel.protocols import Shipment, ShipmentRepository
+from sendparcel.provider import (
+    BaseProvider,
+    CancellableProvider,
+    LabelProvider,
+    PullStatusProvider,
+    PushCallbackProvider,
+)
+from sendparcel.registry import PluginRegistry
+from sendparcel.registry import registry as default_registry
+from sendparcel.types import (
+    AddressInfo,
+    CreateLabelOutcome,
+    CreateShipmentOutcome,
+    ParcelInfo,
+    ShipmentUpdateOutcome,
+    ShipmentUpdateResult,
 )
-from sendparcel.protocols import Order, Shipment, ShipmentRepository
-from sendparcel.registry import registry
 from sendparcel.validators import run_validators
 
 
@@ -23,100 +40,233 @@ class ShipmentFlow:
     def __init__(
         self,
         repository: ShipmentRepository,
-        config: dict | None = None,
-        validators: list | None = None,
+        config: dict[str, Any] | None = None,
+        validators: list[Any] | None = None,
+        registry: PluginRegistry | None = None,
     ) -> None:
         self.repository = repository
         self.config = config or {}
         self.validators = validators or []
+        self.registry = registry or default_registry
 
     async def create_shipment(
         self,
-        order: Order,
         provider_slug: str,
-        **kwargs,
-    ) -> Shipment:
-        """Create a shipment record for an order."""
-        registry.get_by_slug(provider_slug)
-        shipment = await self.repository.create(
-            order=order,
-            provider=provider_slug,
-            status=ShipmentStatus.NEW,
-            **kwargs,
-        )
-        create_shipment_machine(shipment)
+        *,
+        sender_address: AddressInfo,
+        receiver_address: AddressInfo,
+        parcels: list[ParcelInfo],
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> CreateShipmentOutcome:
+        """Create a shipment record with explicit address and parcel data.
+
+        Uses persistence-enforced idempotency: if a shipment with the same
+        provider + idempotency_key already exists, it is returned without
+        calling the provider again.
+
+        On provider failure:
+        - CommunicationError (timeout, network): marks shipment as
+          ``SUBMITTED`` (ambiguous — provider may have accepted).
+          The caller should reconcile via polling or callback.
+        - Other errors: marks shipment as ``FAILED`` and re-raises.
+
+        The shipment record is never deleted on failure, ensuring that
+        retries and reconciliation always have a record to work with.
+
+        Args:
+            provider_slug: Provider identifier.
+            sender_address: Sender address info.
+            receiver_address: Receiver address info.
+            parcels: List of parcel definitions.
+            idempotency_key: Optional key for retry safety. Stored in the
+                ``reference_id`` field of the shipment record.
+            **kwargs: Passed to the provider (after repo-only fields
+                are stripped).
+
+        Returns:
+            CreateShipmentOutcome with the persisted shipment and
+            optional label payload.
+        """
+        self.registry.get_by_slug(provider_slug)
+
+        # Separate repository kwargs from provider kwargs.
+        repo_kwargs: dict[str, Any] = {}
+        for key in ("reference_id",):
+            if key in kwargs:
+                repo_kwargs[key] = kwargs.pop(key)
+
+        # Apply idempotency key to reference_id if provided.
+        if idempotency_key is not None:
+            repo_kwargs.setdefault("reference_id", idempotency_key)
+
+        # Create shipment — use atomic idempotency if key provided.
+        if idempotency_key is not None:
+            (
+                existing,
+                created,
+            ) = await self.repository.create_with_idempotency_key(
+                provider=provider_slug,
+                status=ShipmentStatus.NEW.value,
+                **repo_kwargs,
+            )
+            if existing is not None:
+                return CreateShipmentOutcome(shipment=existing, label=None)
+            if created is None:
+                raise RuntimeError(
+                    "create_with_idempotency_key returned (None, None) "
+                    "— repository contract violated"
+                )
+            shipment = created
+        else:
+            shipment = await self.repository.create(
+                provider=provider_slug,
+                status=ShipmentStatus.NEW.value,
+                **repo_kwargs,
+            )
+
         provider = self._get_provider(shipment)
-        result = await self._call_provider(provider.create_shipment(**kwargs))
-        shipment.external_id = result.get("external_id", "")
-        shipment.tracking_number = result.get("tracking_number", "")
-        self._trigger(shipment, "confirm_created")
-        label = result.get("label") or {}
-        label_url = label.get("url", "")
-        if label_url:
-            shipment.label_url = label_url
-            if shipment.may_trigger("confirm_label"):  # ty: ignore[unresolved-attribute]  # dynamic FSM trigger guard
-                shipment.confirm_label()  # ty: ignore[unresolved-attribute]  # dynamic FSM trigger
-        return await self.repository.save(shipment)
-
-    async def create_label(self, shipment: Shipment, **kwargs) -> Shipment:
-        """Create provider label and persist shipment."""
+        try:
+            result = await self._call_provider(
+                provider.create_shipment(
+                    sender_address=sender_address,
+                    receiver_address=receiver_address,
+                    parcels=parcels,
+                    **kwargs,
+                )
+            )
+        except CommunicationError:
+            # Ambiguous: provider may have accepted the shipment
+            # (e.g. timeout after acceptance). Mark as SUBMITTED for
+            # reconciliation via polling or callback.
+            transition_shipment(shipment, ShipmentStatus.SUBMITTED)
+            await self.repository.save(shipment)
+            return CreateShipmentOutcome(shipment=shipment, label=None)
+        except Exception:
+            # Non-communication error: mark as FAILED, never delete.
+            transition_shipment(shipment, ShipmentStatus.FAILED)
+            await self.repository.save(shipment)
+            raise
+
+        shipment.external_id = str(result.get("external_id", ""))
+        shipment.tracking_number = str(result.get("tracking_number", ""))
+        transition_shipment(shipment, ShipmentStatus.CREATED)
+        label = result.get("label")
+        if label is not None:
+            transition_shipment(shipment, ShipmentStatus.LABEL_READY)
+        saved = await self.repository.save(shipment)
+        return CreateShipmentOutcome(shipment=saved, label=label)
+
+    async def create_label(
+        self, shipment: Shipment, **kwargs: Any
+    ) -> CreateLabelOutcome:
+        """Create provider label and persist shipment metadata."""
+
         run_validators({"shipment": shipment}, validators=self.validators)
-        create_shipment_machine(shipment)
         provider = self._get_provider(shipment)
+        if not isinstance(provider, LabelProvider):
+            raise ProviderCapabilityError(
+                f"Provider {shipment.provider!r} does not support "
+                "label creation"
+            )
         label = await self._call_provider(provider.create_label(**kwargs))
-        shipment.label_url = label.get("url", "")
-        if shipment.may_trigger("confirm_label"):  # ty: ignore[unresolved-attribute]  # dynamic FSM trigger guard
-            shipment.confirm_label()  # ty: ignore[unresolved-attribute]  # dynamic FSM trigger
-        return await self.repository.save(shipment)
+        transition_shipment(shipment, ShipmentStatus.LABEL_READY)
+        saved = await self.repository.update_fields(
+            shipment_id=shipment.id, status=shipment.status
+        )
+        return CreateLabelOutcome(shipment=saved, label=label)
 
     async def handle_callback(
         self,
         shipment: Shipment,
-        data: dict,
-        headers: dict,
-        **kwargs,
-    ) -> Shipment:
+        data: dict[str, Any],
+        headers: dict[str, Any],
+        **kwargs: Any,
+    ) -> ShipmentUpdateOutcome:
         """Verify and apply provider callback."""
+
         provider = self._get_provider(shipment)
-        create_shipment_machine(shipment)
+        if not isinstance(provider, PushCallbackProvider):
+            raise ProviderCapabilityError(
+                f"Provider {shipment.provider!r} does not support "
+                "push callbacks"
+            )
         await self._call_provider(
             provider.verify_callback(data, headers, **kwargs)
         )
-        await self._call_provider(
+        update = await self._call_provider(
             provider.handle_callback(data, headers, **kwargs)
         )
-        return await self.repository.save(shipment)
+        normalized_update = update or ShipmentUpdateResult()
+        saved = await self._apply_update(shipment, normalized_update)
+        return ShipmentUpdateOutcome(shipment=saved, update=normalized_update)
 
-    async def fetch_and_update_status(self, shipment: Shipment) -> Shipment:
+    async def fetch_and_update_status(
+        self, shipment: Shipment
+    ) -> ShipmentUpdateOutcome:
         """Fetch status from provider and persist."""
+
         provider = self._get_provider(shipment)
-        create_shipment_machine(shipment)
-        response = await self._call_provider(provider.fetch_shipment_status())
-        status_value = response.get("status")
-        callback = self._resolve_callback(status_value)
-        if callback:
-            self._trigger(shipment, callback)
-        return await self.repository.save(shipment)
-
-    async def cancel_shipment(self, shipment: Shipment, **kwargs) -> bool:
+        if not isinstance(provider, PullStatusProvider):
+            raise ProviderCapabilityError(
+                f"Provider {shipment.provider!r} does not support "
+                "status polling"
+            )
+        update = await self._call_provider(provider.fetch_shipment_status())
+        normalized_update = update or ShipmentUpdateResult()
+        saved = await self._apply_update(shipment, normalized_update)
+        return ShipmentUpdateOutcome(shipment=saved, update=normalized_update)
+
+    async def cancel_shipment(self, shipment: Shipment, **kwargs: Any) -> bool:
         """Cancel shipment via provider and persist state."""
+
         provider = self._get_provider(shipment)
-        create_shipment_machine(shipment)
+        if not isinstance(provider, CancellableProvider):
+            raise ProviderCapabilityError(
+                f"Provider {shipment.provider!r} does not support cancellation"
+            )
         cancelled = await self._call_provider(
             provider.cancel_shipment(**kwargs)
         )
         if cancelled:
-            self._trigger(shipment, "cancel")
-            await self.repository.save(shipment)
-        return cancelled
+            transition_shipment(shipment, ShipmentStatus.CANCELLED)
+            await self.repository.update_fields(
+                shipment_id=shipment.id, status=shipment.status
+            )
+        return bool(cancelled)
 
-    def _get_provider(self, shipment: Shipment):
-        provider_class = registry.get_by_slug(shipment.provider)
+    def _get_provider(self, shipment: Shipment) -> BaseProvider:
+        provider_class = self.registry.get_by_slug(shipment.provider)
         provider_config = self.config.get(shipment.provider, {})
         return provider_class(shipment, config=provider_config)
 
-    async def _call_provider(self, coro):
-        """Call a provider coroutine, wrapping non-domain errors."""
+    async def _apply_update(
+        self, shipment: Shipment, update: ShipmentUpdateResult
+    ) -> Shipment:
+        """Apply a normalized update to a shipment atomically.
+
+        Uses the atomic ``update_fields`` persistence primitive to
+        prevent concurrent read-modify-save races.
+        """
+        fields: dict[str, Any] = {}
+        tracking_number = update.get("tracking_number")
+        if tracking_number:
+            fields["tracking_number"] = str(tracking_number)
+        status = update.get("status")
+        if status is not None:
+            transition_shipment(shipment, status)
+            fields["status"] = shipment.status
+        return await self.repository.update_fields(
+            shipment_id=shipment.id, **fields
+        )
+
+    async def _call_provider(self, coro: Any) -> Any:
+        """Call a provider coroutine, wrapping only network errors.
+
+        Domain errors (ValueError, KeyError, TypeError, etc.) are re-raised
+        as-is so they are distinguishable from communication failures.
+        """
+
         try:
             return await coro
         except SendParcelException:
@@ -126,39 +276,19 @@ class ShipmentFlow:
                 str(exc),
                 context={"original_error": type(exc).__name__},
             ) from exc
-        except Exception as exc:
+        except TimeoutError as exc:
+            raise CommunicationError(
+                str(exc),
+                context={"original_error": type(exc).__name__},
+            ) from exc
+        except ExceptionGroup as exc:
+            # Preserve typed inner exceptions: if any inner exception is a
+            # SendParcelException, re-raise it directly. Otherwise wrap the
+            # entire group in a CommunicationError.
+            for e in exc.exceptions:
+                if isinstance(e, SendParcelException):
+                    raise e from exc
             raise CommunicationError(
                 str(exc),
                 context={"original_error": type(exc).__name__},
             ) from exc
-
-    def _resolve_callback(self, status_value: str | None) -> str | None:
-        """Map a provider status value to an FSM callback name.
-
-        Only accepts values from STATUS_TO_CALLBACK mapping.
-        Raw callback names (e.g., "cancel") are NOT accepted as
-        status values -- providers must return status enum values
-        (e.g., "cancelled").
-        """
-        if status_value is None:
-            return None
-        callback = STATUS_TO_CALLBACK.get(status_value)
-        if callback:
-            return callback
-        raise InvalidTransitionError(
-            f"Unknown status value {status_value!r}. "
-            f"Expected one of: {', '.join(sorted(STATUS_TO_CALLBACK))}"
-        )
-
-    def _trigger(self, shipment: Shipment, callback: str, **kwargs) -> None:
-        trigger = getattr(shipment, callback, None)
-        if trigger is None or not callable(trigger):
-            raise InvalidTransitionError(
-                f"Shipment has no callback trigger {callback!r}"
-            )
-        if not shipment.may_trigger(callback):  # ty: ignore[unresolved-attribute]  # dynamic FSM trigger guard
-            raise InvalidTransitionError(
-                f"Callback {callback!r} cannot be executed from status "
-                f"{shipment.status!r}"
-            )
-        trigger(**kwargs)

sendparcel/fsm.py

@@ -1,131 +1,106 @@
-"""Shipment state machine definitions."""
+"""Explicit shipment status transitions."""
 
-from transitions import Machine
-from transitions.core import MachineError
+from __future__ import annotations
 
 from sendparcel.enums import ShipmentStatus
+from sendparcel.exceptions import InvalidTransitionError
+from sendparcel.protocols import Shipment
 
-CALLBACK_NAMES = (
-    "confirm_created",
-    "confirm_label",
-    "mark_in_transit",
-    "mark_out_for_delivery",
-    "mark_delivered",
-    "mark_returned",
-    "cancel",
-    "fail",
-)
-
-
-def _require_label_url(event_data):
-    """Guard: reject confirm_label if shipment has no label_url."""
-    model = event_data.model
-    if not getattr(model, "label_url", ""):
-        raise MachineError(
-            f"Transition '{event_data.event.name}'"
-            " requires label_url to be set."
-        )
-
-
-def _require_tracking_number(event_data):
-    """Guard: reject mark_in_transit if shipment has no tracking_number."""
-    model = event_data.model
-    if not getattr(model, "tracking_number", ""):
-        raise MachineError(
-            f"Transition '{event_data.event.name}'"
-            " requires tracking_number to be set."
-        )
-
-
-SHIPMENT_TRANSITIONS = [
-    {
-        "trigger": "confirm_created",
-        "source": ShipmentStatus.NEW,
-        "dest": ShipmentStatus.CREATED,
-    },
-    {
-        "trigger": "confirm_label",
-        "source": ShipmentStatus.CREATED,
-        "dest": ShipmentStatus.LABEL_READY,
-        "before": _require_label_url,
-    },
-    {
-        "trigger": "mark_in_transit",
-        "source": [ShipmentStatus.CREATED, ShipmentStatus.LABEL_READY],
-        "dest": ShipmentStatus.IN_TRANSIT,
-        "before": _require_tracking_number,
-    },
-    {
-        "trigger": "mark_out_for_delivery",
-        "source": ShipmentStatus.IN_TRANSIT,
-        "dest": ShipmentStatus.OUT_FOR_DELIVERY,
-    },
-    {
-        "trigger": "mark_delivered",
-        "source": [
+ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
+    ShipmentStatus.NEW: frozenset(
+        {
+            ShipmentStatus.CREATED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
+            ShipmentStatus.SUBMITTED,
+        }
+    ),
+    ShipmentStatus.CREATED: frozenset(
+        {
+            ShipmentStatus.LABEL_READY,
             ShipmentStatus.IN_TRANSIT,
             ShipmentStatus.OUT_FOR_DELIVERY,
-        ],
-        "dest": ShipmentStatus.DELIVERED,
-    },
-    {
-        "trigger": "mark_returned",
-        "source": [
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+    ShipmentStatus.LABEL_READY: frozenset(
+        {
             ShipmentStatus.IN_TRANSIT,
             ShipmentStatus.OUT_FOR_DELIVERY,
             ShipmentStatus.DELIVERED,
-        ],
-        "dest": ShipmentStatus.RETURNED,
-    },
-    {
-        "trigger": "cancel",
-        "source": [
-            ShipmentStatus.NEW,
-            ShipmentStatus.CREATED,
-            ShipmentStatus.LABEL_READY,
-        ],
-        "dest": ShipmentStatus.CANCELLED,
-    },
-    {
-        "trigger": "fail",
-        "source": [
-            ShipmentStatus.NEW,
-            ShipmentStatus.CREATED,
-            ShipmentStatus.LABEL_READY,
-            ShipmentStatus.IN_TRANSIT,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+    ShipmentStatus.IN_TRANSIT: frozenset(
+        {
             ShipmentStatus.OUT_FOR_DELIVERY,
-        ],
-        "dest": ShipmentStatus.FAILED,
-    },
-]
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+    ShipmentStatus.OUT_FOR_DELIVERY: frozenset(
+        {
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+    ShipmentStatus.DELIVERED: frozenset({ShipmentStatus.RETURNED}),
+    ShipmentStatus.CANCELLED: frozenset(),
+    ShipmentStatus.FAILED: frozenset(),
+    ShipmentStatus.RETURNED: frozenset(),
+    ShipmentStatus.SUBMITTED: frozenset(
+        {
+            ShipmentStatus.CREATED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+}
 
-ALLOWED_CALLBACKS: frozenset[str] = frozenset(CALLBACK_NAMES)
 
-STATUS_TO_CALLBACK: dict[str, str] = {
-    ShipmentStatus.CREATED.value: "confirm_created",
-    ShipmentStatus.LABEL_READY.value: "confirm_label",
-    ShipmentStatus.IN_TRANSIT.value: "mark_in_transit",
-    ShipmentStatus.OUT_FOR_DELIVERY.value: "mark_out_for_delivery",
-    ShipmentStatus.DELIVERED.value: "mark_delivered",
-    ShipmentStatus.RETURNED.value: "mark_returned",
-    ShipmentStatus.CANCELLED.value: "cancel",
-    ShipmentStatus.FAILED.value: "fail",
-}
+def normalize_status(status: str | ShipmentStatus) -> ShipmentStatus:
+    """Normalise a status to a :class:`ShipmentStatus` enum member."""
 
+    try:
+        return ShipmentStatus(status)
+    except ValueError as exc:
+        raise InvalidTransitionError(
+            f"Unknown shipment status {status!r}"
+        ) from exc
 
-def create_shipment_machine(shipment) -> Machine:
-    """Attach shipment FSM to shipment object."""
-    initial = (
-        ShipmentStatus(shipment.status)
-        if shipment.status
-        else ShipmentStatus.NEW
-    )
-    return Machine(
-        model=shipment,
-        states=ShipmentStatus,
-        transitions=SHIPMENT_TRANSITIONS,
-        initial=initial,
-        model_attribute="status",
-        auto_transitions=False,
-        send_event=True,
-    )
+
+def can_transition(
+    current_status: str | ShipmentStatus,
+    target_status: str | ShipmentStatus,
+) -> bool:
+    """Check whether a shipment status transition is allowed."""
+
+    current = normalize_status(current_status)
+    target = normalize_status(target_status)
+    if current == target:
+        return True
+    return target in ALLOWED_STATUS_TRANSITIONS[current]
+
+
+def transition_shipment(
+    shipment: Shipment, target_status: str | ShipmentStatus
+) -> Shipment:
+    """Apply a validated status transition to a shipment."""
+
+    current = normalize_status(shipment.status)
+    target = normalize_status(target_status)
+    if current == target:
+        shipment.status = target.value
+        return shipment
+    if target not in ALLOWED_STATUS_TRANSITIONS[current]:
+        raise InvalidTransitionError(
+            f"Shipment cannot transition from {current!r} to {target!r}"
+        )
+    shipment.status = target.value
+    return shipment