python-sendparcel 0.3.0__tar.gz → 0.3.1__tar.gz

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.3.0
+Version: 0.3.1
 Summary: Framework-agnostic parcel shipping core for Python.
 Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel
 Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-sendparcel"
-version = "0.3.0"
+version = "0.3.1"
 description = "Framework-agnostic parcel shipping core for Python."
 readme = "README.md"
 license = { text = "MIT" }

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/src/sendparcel/__init__.py

@@ -21,8 +21,13 @@ from sendparcel.providers.dummy import DummyProvider
 from sendparcel.registry import registry
 from sendparcel.types import (
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     CreateLabelOutcome,
     CreateShipmentOutcome,
+    GeoPoint,
+    PickupPoint,
+    Quote,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
@@ -32,16 +37,21 @@ __all__ = [
     "BatchCreateResult",
     "BatchResult",
     "CallbackContext",
+    "CancelOutcome",
+    "CancelReason",
     "CommunicationError",
     "ConfirmationMethod",
     "CreateLabelOutcome",
     "CreateShipmentOutcome",
     "DummyProvider",
+    "GeoPoint",
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LabelFormat",
+    "PickupPoint",
     "ProviderCapabilityError",
     "ProviderNotFoundError",
+    "Quote",
     "SendParcelException",
     "ShipmentBatch",
     "ShipmentFlow",

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/src/sendparcel/flow.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 import httpx
@@ -19,14 +20,30 @@ from sendparcel.registry import registry as default_registry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     CreateLabelOutcome,
     CreateShipmentOutcome,
+    GeoPoint,
     ParcelInfo,
+    PickupPoint,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
 
 
+@dataclass(slots=True)
+class _PointSearchShipment:
+    """Placeholder satisfying the Shipment protocol for provider calls
+    that do not operate on a specific shipment (e.g. point search)."""
+
+    provider: str
+    id: str = ""
+    status: str = "new"
+    external_id: str = ""
+    tracking_number: str = ""
+
+
 class ShipmentFlow:
     """Framework-agnostic shipment orchestration."""
 
@@ -193,19 +210,87 @@ class ShipmentFlow:
         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."""
-
+    async def cancel_shipment(
+        self, shipment: Shipment, **kwargs: Any
+    ) -> CancelOutcome:
+        """Cancel shipment via provider and persist state.
+
+        Returns a structured :class:`CancelOutcome` so callers can
+        distinguish permanent denies from retryable failures.
+
+        - ``CANCELLED`` / ``ALREADY_CANCELLED`` → transitions shipment to
+          ``CANCELLED``.
+        - ``REFUSED_IN_TRANSIT`` / ``NOT_CANCELLABLE`` → leaves shipment
+          in current state (caller decides UX).
+        - ``TRANSIENT_ERROR`` → raises ``CommunicationError`` (retryable),
+          no state change.
+        - ``AUTH_ERROR`` → re-raises provider auth error.
+        """
         provider = self._get_provider(shipment)
-        cancelled = await self._call_provider(
-            provider.cancel_shipment(**kwargs)
-        )
-        if cancelled:
+        outcome = await self._call_provider(provider.cancel_shipment(**kwargs))
+        if outcome.get("reason") == CancelReason.TRANSIENT_ERROR:
+            raise CommunicationError(
+                outcome.get("detail") or "Cancel failed with transient error",
+                context={
+                    "provider_status_code": outcome.get("provider_status_code"),
+                    "reason": CancelReason.TRANSIENT_ERROR,
+                },
+            )
+        if outcome.get("cancelled"):
             transition_shipment(shipment, ShipmentStatus.CANCELLED)
             await self.repository.update_fields(
                 shipment_id=shipment.id, status=shipment.status
             )
-        return bool(cancelled)
+        return outcome
+
+    async def search_points(
+        self,
+        provider_slug: str,
+        *,
+        query: str | None = None,
+        near: GeoPoint | None = None,
+        radius_m: int | None = None,
+        point_type: str | None = None,
+        limit: int = 20,
+        **kwargs: Any,
+    ) -> list[PickupPoint]:
+        """Search carrier pickup points via the registered provider.
+
+        Convenience method that delegates to the provider's
+        ``search_points`` capability. Raises
+        ``ProviderCapabilityError`` if the provider does not support
+        point search.
+
+        Args:
+            provider_slug: Provider identifier.
+            query: Free-text search (city, address, or point code).
+            near: :class:`GeoPoint` for proximity search.
+            radius_m: Search radius in metres when ``near`` is given.
+            point_type: Provider taxonomy filter.
+            limit: Maximum number of results.
+
+        Returns:
+            List of :class:`PickupPoint` results.
+        """
+        provider_class = self.registry.get_by_slug(provider_slug)
+        provider_config = self.config.get(provider_slug, {})
+        from sendparcel.factory import create_provider
+
+        provider = create_provider(
+            _PointSearchShipment(provider=provider_slug),
+            provider_class,
+            provider_config,
+        )
+        return await self._call_provider(
+            provider.search_points(
+                query=query,
+                near=near,
+                radius_m=radius_m,
+                point_type=point_type,
+                limit=limit,
+                **kwargs,
+            )
+        )
 
     def _get_provider(self, shipment: Shipment) -> BaseProvider:
         from sendparcel.factory import create_provider

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/src/sendparcel/provider.py

@@ -12,8 +12,12 @@ from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    GeoPoint,
     LabelInfo,
     ParcelInfo,
+    PickupPoint,
+    Quote,
     ShipmentCreateResult,
     ShipmentUpdateResult,
 )
@@ -230,9 +234,13 @@ class BaseProvider(ABC):
             "status polling"
         )
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
         """Cancel shipment if provider supports cancellation.
 
+        Returns a structured :class:`CancelOutcome` so callers can
+        distinguish permanent denies (REFUSED_IN_TRANSIT, NOT_CANCELLABLE)
+        from retryable failures (TRANSIENT_ERROR).
+
         Raises :exc:`ProviderCapabilityError` if the provider does not
         support cancellation.
         """
@@ -240,3 +248,63 @@ class BaseProvider(ABC):
             f"Provider {self.__class__.__name__!r} does not support "
             "cancellation"
         )
+
+    async def search_points(
+        self,
+        *,
+        query: str | None = None,
+        near: GeoPoint | None = None,
+        radius_m: int | None = None,
+        point_type: str | None = None,
+        limit: int = 20,
+        **kwargs: Any,
+    ) -> list[PickupPoint]:
+        """Search carrier pickup points (lockers, parcel shops, etc.).
+
+        Args:
+            query: Free-text search (city, address, or point code).
+            near: :class:`GeoPoint` for proximity search.
+            radius_m: Search radius in metres when ``near`` is given.
+            point_type: Provider taxonomy filter (e.g. "parcel_locker").
+            limit: Maximum number of results to return.
+
+        Returns:
+            List of :class:`PickupPoint` results, ordered by distance
+            when ``near`` is given, else by relevance/name.
+
+        Raises:
+            ProviderCapabilityError: If the provider does not support
+                point search.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "pickup point search"
+        )
+
+    async def get_quote(
+        self,
+        *,
+        service: str,
+        parcels: list[ParcelInfo],
+        sender_address: AddressInfo | None = None,
+        receiver_address: AddressInfo | None = None,
+        **kwargs: Any,
+    ) -> Quote:
+        """Get a shipping rate quote for a service/route combination.
+
+        Args:
+            service: Service slug (e.g. "parcel_locker_31_0").
+            parcels: List of parcel definitions.
+            sender_address: Optional sender address.
+            receiver_address: Optional receiver address.
+
+        Returns:
+            :class:`Quote` with carrier cost as ``Decimal``.
+
+        Raises:
+            ProviderCapabilityError: If the provider does not support
+                rate lookup (callers should fall back to static pricing).
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support rate lookup"
+        )

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/src/sendparcel/types.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import hashlib
 import json
 from dataclasses import dataclass
+from datetime import datetime
 from decimal import Decimal
+from enum import StrEnum
 from typing import Any, TypedDict
 
 from sendparcel.enums import LabelFormat
@@ -107,6 +109,81 @@ class ShipmentUpdateOutcome:
     update: ShipmentUpdateResult
 
 
+class CancelReason(StrEnum):
+    """Reason for a cancel_shipment outcome."""
+
+    CANCELLED = "cancelled"
+    ALREADY_CANCELLED = "already_cancelled"
+    REFUSED_IN_TRANSIT = "refused_in_transit"
+    NOT_CANCELLABLE = "not_cancellable"
+    TRANSIENT_ERROR = "transient_error"
+    AUTH_ERROR = "auth_error"
+
+
+class _CancelOutcomeRequired(TypedDict):
+    cancelled: bool
+    reason: CancelReason
+    retryable: bool
+
+
+class CancelOutcome(_CancelOutcomeRequired, total=False):
+    """Structured result from cancel_shipment.
+
+    Replaces the bare bool return so callers can distinguish permanent
+    denies (REFUSED_IN_TRANSIT, NOT_CANCELLABLE) from retryable failures
+    (TRANSIENT_ERROR).
+    """
+
+    provider_status_code: int | None
+    detail: str | None
+
+
+class GeoPoint(TypedDict):
+    """Geographic coordinate pair."""
+
+    lat: float
+    lng: float
+
+
+class _PickupPointRequired(TypedDict):
+    code: str
+    name: str
+    provider_slug: str
+    address: str
+
+
+class PickupPoint(_PickupPointRequired, total=False):
+    """Carrier pickup point (locker, parcel shop, etc.).
+
+    ``code`` is the machine id used as ``target_point`` in
+    ``create_shipment``, so a searched point is directly usable
+    without translation.
+    """
+
+    location: GeoPoint | None
+    opening_hours: str | None
+    point_type: str | None
+    raw: dict[str, Any] | None
+
+
+class _QuoteRequired(TypedDict):
+    provider_slug: str
+    service: str
+    amount: Decimal
+    currency: str
+
+
+class Quote(_QuoteRequired, total=False):
+    """Shipping rate quote from a carrier.
+
+    ``amount`` is the carrier cost in the provider's currency.
+    Use ``Decimal`` — never ``float`` — for monetary values.
+    """
+
+    valid_until: datetime | None
+    raw: dict[str, Any] | None
+
+
 @dataclass(slots=True)
 class CallbackContext:
     """Everything needed to process a webhook callback.

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/tests/test_batch.py

@@ -15,6 +15,8 @@ from sendparcel.registry import PluginRegistry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     ParcelInfo,
     ShipmentCreateResult,
     ShipmentUpdateResult,
@@ -168,8 +170,14 @@ class DummyProvider(BaseProvider):
     ) -> ShipmentUpdateResult:
         return {"status": ShipmentStatus.CREATED}
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
-        return True
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        return CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.CANCELLED,
+            retryable=False,
+            provider_status_code=200,
+            detail=None,
+        )
 
 
 @pytest.fixture

python_sendparcel-0.3.1/tests/test_cancel_outcome.py

@@ -0,0 +1,320 @@
+"""Tests for CancelOutcome and cancel_shipment result semantics."""
+
+from __future__ import annotations
+
+import pytest
+
+from sendparcel.enums import ShipmentStatus
+from sendparcel.exceptions import CommunicationError
+from sendparcel.flow import ShipmentFlow
+from sendparcel.provider import BaseProvider
+from sendparcel.types import (
+    AddressInfo,
+    CancelOutcome,
+    CancelReason,
+    ParcelInfo,
+    ShipmentCreateResult,
+)
+
+
+class CancelOutcomeTestProvider(BaseProvider):
+    """Provider that returns configurable CancelOutcome."""
+
+    slug = "cancel_test"
+    display_name = "Cancel Test"
+    cancel_result: CancelOutcome | Exception | None = None
+
+    async def create_shipment(
+        self,
+        *,
+        sender_address: AddressInfo,
+        receiver_address: AddressInfo,
+        parcels: list[ParcelInfo],
+        **kwargs,
+    ) -> ShipmentCreateResult:
+        return {"external_id": "ext-1"}
+
+    async def cancel_shipment(self, **kwargs) -> CancelOutcome:
+        if isinstance(self.cancel_result, Exception):
+            raise self.cancel_result
+        if self.cancel_result is None:
+            raise NotImplementedError("cancel_result not configured")
+        return self.cancel_result
+
+
+class DummyShipment:
+    def __init__(self, status=ShipmentStatus.CREATED) -> None:
+        self.id = "ship-1"
+        self.status = status
+        self.provider = "cancel_test"
+        self.external_id = "12345"
+        self.tracking_number = "TRK-123"
+
+
+class DummyRepo:
+    def __init__(self) -> None:
+        self.shipment = DummyShipment()
+        self.updated_shipment: DummyShipment | None = None
+
+    async def create(self, **kwargs) -> DummyShipment:
+        return self.shipment
+
+    async def save(self, shipment: DummyShipment) -> DummyShipment:
+        return shipment
+
+    async def update_status(self, shipment_id: str, status: str, **fields):
+        return self.shipment
+
+    async def update_fields(self, shipment_id: str, **fields) -> DummyShipment:
+        for key, value in fields.items():
+            setattr(self.shipment, key, value)
+        self.updated_shipment = self.shipment
+        return self.shipment
+
+    async def delete(self, shipment_id: str) -> None:
+        pass
+
+    async def find_by_reference(self, provider: str, reference_id: str):
+        return self.shipment
+
+    async def create_with_idempotency_key(
+        self, provider: str, status: str, reference_id: str, **kwargs
+    ):
+        return (None, self.shipment)
+
+    def get_by_id_sync(self, shipment_id: str, *, for_update: bool = False):
+        return self.shipment
+
+    async def get_by_id(self, shipment_id: str, *, for_update: bool = False):
+        return self.shipment
+
+
+def _make_flow(
+    provider: type[CancelOutcomeTestProvider],
+) -> tuple[ShipmentFlow, CancelOutcomeTestProvider, DummyRepo]:
+    from sendparcel.registry import PluginRegistry
+
+    registry = PluginRegistry()
+    registry.register(provider)
+    repo = DummyRepo()
+    flow = ShipmentFlow(repository=repo, registry=registry)
+    instance = provider(shipment=repo.shipment)
+    return flow, instance, repo
+
+
+class TestCancelReason:
+    """CancelReason enum tests."""
+
+    def test_cancelled_value(self) -> None:
+        assert CancelReason.CANCELLED == "cancelled"
+
+    def test_already_cancelled_value(self) -> None:
+        assert CancelReason.ALREADY_CANCELLED == "already_cancelled"
+
+    def test_refused_in_transit_value(self) -> None:
+        assert CancelReason.REFUSED_IN_TRANSIT == "refused_in_transit"
+
+    def test_not_cancellable_value(self) -> None:
+        assert CancelReason.NOT_CANCELLABLE == "not_cancellable"
+
+    def test_transient_error_value(self) -> None:
+        assert CancelReason.TRANSIENT_ERROR == "transient_error"
+
+    def test_auth_error_value(self) -> None:
+        assert CancelReason.AUTH_ERROR == "auth_error"
+
+
+class TestCancelOutcome:
+    """CancelOutcome TypedDict tests."""
+
+    def test_successful_cancel(self) -> None:
+        outcome: CancelOutcome = {
+            "cancelled": True,
+            "reason": CancelReason.CANCELLED,
+            "retryable": False,
+            "provider_status_code": 200,
+            "detail": None,
+        }
+        assert outcome["cancelled"] is True
+        assert outcome["retryable"] is False
+
+    def test_already_cancelled(self) -> None:
+        outcome: CancelOutcome = {
+            "cancelled": True,
+            "reason": CancelReason.ALREADY_CANCELLED,
+            "retryable": False,
+            "provider_status_code": 404,
+            "detail": None,
+        }
+        assert outcome["cancelled"] is True
+        assert outcome["reason"] == CancelReason.ALREADY_CANCELLED
+
+    def test_refused_in_transit(self) -> None:
+        outcome: CancelOutcome = {
+            "cancelled": False,
+            "reason": CancelReason.REFUSED_IN_TRANSIT,
+            "retryable": False,
+            "provider_status_code": 400,
+            "detail": "Shipment already in transit",
+        }
+        assert outcome["cancelled"] is False
+        assert outcome["retryable"] is False
+
+    def test_transient_error(self) -> None:
+        outcome: CancelOutcome = {
+            "cancelled": False,
+            "reason": CancelReason.TRANSIENT_ERROR,
+            "retryable": True,
+            "provider_status_code": 503,
+            "detail": "Service unavailable",
+        }
+        assert outcome["cancelled"] is False
+        assert outcome["retryable"] is True
+
+
+class TestFlowCancelShipment:
+    """ShipmentFlow.cancel_shipment integration tests."""
+
+    async def test_successful_cancel_transitions_to_cancelled(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.CANCELLED,
+            retryable=False,
+            provider_status_code=200,
+            detail=None,
+        )
+        flow, _, repo = _make_flow(provider_class)
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is True
+        assert result["reason"] == CancelReason.CANCELLED
+        assert repo.shipment.status == ShipmentStatus.CANCELLED
+
+    async def test_already_cancelled_transitions_to_cancelled(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.ALREADY_CANCELLED,
+            retryable=False,
+            provider_status_code=404,
+            detail=None,
+        )
+        flow, _, repo = _make_flow(provider_class)
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is True
+        assert result["reason"] == CancelReason.ALREADY_CANCELLED
+        assert repo.shipment.status == ShipmentStatus.CANCELLED
+
+    async def test_refused_in_transit_leaves_state_unchanged(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=False,
+            reason=CancelReason.REFUSED_IN_TRANSIT,
+            retryable=False,
+            provider_status_code=400,
+            detail="Shipment already dispatched",
+        )
+        flow, _, repo = _make_flow(provider_class)
+        repo.shipment.status = ShipmentStatus.CREATED
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is False
+        assert result["retryable"] is False
+        assert repo.shipment.status == ShipmentStatus.CREATED
+
+    async def test_not_cancellable_leaves_state_unchanged(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=False,
+            reason=CancelReason.NOT_CANCELLABLE,
+            retryable=False,
+            provider_status_code=422,
+            detail="Cannot cancel collected shipment",
+        )
+        flow, _, repo = _make_flow(provider_class)
+        original_status = ShipmentStatus.LABEL_READY
+        repo.shipment.status = original_status
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is False
+        assert repo.shipment.status == original_status
+
+    async def test_transient_error_raises_communication_error(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CommunicationError(
+            "API timeout",
+            context={"retryable": True},
+        )
+        flow, _, repo = _make_flow(provider_class)
+        original_status = ShipmentStatus.CREATED
+        repo.shipment.status = original_status
+
+        with pytest.raises(CommunicationError):
+            await flow.cancel_shipment(repo.shipment)
+
+        # State should not change on transient failure
+        assert repo.shipment.status == original_status
+
+    async def test_transient_error_outcome_raises_communication_error(
+        self,
+    ) -> None:
+        """A provider returning a TRANSIENT_ERROR outcome (instead of
+        raising) must still surface as CommunicationError from the flow,
+        so callers get one retryable signal regardless of provider style."""
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=False,
+            reason=CancelReason.TRANSIENT_ERROR,
+            retryable=True,
+            provider_status_code=503,
+            detail="Service unavailable",
+        )
+        flow, _, repo = _make_flow(provider_class)
+        original_status = ShipmentStatus.CREATED
+        repo.shipment.status = original_status
+
+        with pytest.raises(CommunicationError) as exc_info:
+            await flow.cancel_shipment(repo.shipment)
+
+        assert exc_info.value.context["provider_status_code"] == 503
+        assert repo.shipment.status == original_status
+
+    async def test_cancel_from_new_status(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.CANCELLED,
+            retryable=False,
+            provider_status_code=200,
+            detail=None,
+        )
+        flow, _, repo = _make_flow(provider_class)
+        repo.shipment.status = ShipmentStatus.NEW
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is True
+        assert repo.shipment.status == ShipmentStatus.CANCELLED
+
+    async def test_cancel_from_label_ready_status(self) -> None:
+        provider_class = CancelOutcomeTestProvider
+        provider_class.cancel_result = CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.CANCELLED,
+            retryable=False,
+            provider_status_code=200,
+            detail=None,
+        )
+        flow, _, repo = _make_flow(provider_class)
+        repo.shipment.status = ShipmentStatus.LABEL_READY
+
+        result = await flow.cancel_shipment(repo.shipment)
+
+        assert result["cancelled"] is True
+        assert repo.shipment.status == ShipmentStatus.CANCELLED

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/tests/test_flow.py

@@ -20,6 +20,8 @@ from sendparcel.registry import registry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -84,8 +86,19 @@ class FlowProvider(BaseProvider):
             tracking_events=[{"code": "polled"}],
         )
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
-        return bool(self.get_setting("cancel_success", True))
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        success = bool(self.get_setting("cancel_success", True))
+        return CancelOutcome(
+            cancelled=success,
+            reason=(
+                CancelReason.CANCELLED
+                if success
+                else CancelReason.REFUSED_IN_TRANSIT
+            ),
+            retryable=False,
+            provider_status_code=200 if success else 400,
+            detail=None,
+        )
 
 
 class LabelIncludedProvider(BaseProvider):
@@ -377,7 +390,7 @@ class TestCancelShipment:
 
         cancelled = await flow.cancel_shipment(shipment)
 
-        assert cancelled is True
+        assert cancelled["cancelled"] is True
         assert shipment.status == "cancelled"
 
     @pytest.mark.asyncio
@@ -392,7 +405,7 @@ class TestCancelShipment:
 
         cancelled = await flow.cancel_shipment(shipment)
 
-        assert cancelled is False
+        assert cancelled["cancelled"] is False
         assert shipment.status == "created"
 
     @pytest.mark.asyncio

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/tests/test_integration.py

@@ -13,6 +13,8 @@ from sendparcel.registry import registry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -75,8 +77,19 @@ class IntegrationProvider(BaseProvider):
             tracking_events=[{"code": "poll"}],
         )
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
-        return bool(self.get_setting("cancel_success", True))
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        success = bool(self.get_setting("cancel_success", True))
+        return CancelOutcome(
+            cancelled=success,
+            reason=(
+                CancelReason.CANCELLED
+                if success
+                else CancelReason.REFUSED_IN_TRANSIT
+            ),
+            retryable=False,
+            provider_status_code=200 if success else 400,
+            detail=None,
+        )
 
 
 class InlineLabelProvider(IntegrationProvider):
@@ -203,5 +216,5 @@ async def test_cancel_rejection_keeps_current_status() -> None:
 
     cancelled = await flow.cancel_shipment(shipment)
 
-    assert cancelled is False
+    assert cancelled["cancelled"] is False
     assert shipment.status == "created"

{python_sendparcel-0.3.0 → python_sendparcel-0.3.1}/tests/test_public_api.py

@@ -9,11 +9,16 @@ def test_public_api_exports_exact_set() -> None:
         "BaseProvider",
         "BatchCreateResult",
         "BatchResult",
+        "CancelOutcome",
+        "CancelReason",
         "CallbackContext",
         "CommunicationError",
         "ConfirmationMethod",
         "CreateLabelOutcome",
         "CreateShipmentOutcome",
+        "GeoPoint",
+        "PickupPoint",
+        "Quote",
         "DummyProvider",
         "configure_logging",
         "create_provider",

python_sendparcel-0.3.1/tests/test_quote.py

@@ -0,0 +1,87 @@
+"""Tests for get_quote capability."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+from sendparcel.exceptions import ProviderCapabilityError
+from sendparcel.provider import BaseProvider
+from sendparcel.types import (
+    AddressInfo,
+    ParcelInfo,
+    Quote,
+    ShipmentCreateResult,
+)
+
+
+class DummyShipment:
+    id = "ship-1"
+    status = "new"
+    provider = "no-quote"
+    external_id = ""
+    tracking_number = ""
+
+
+class NoQuoteProvider(BaseProvider):
+    """Provider that does not support get_quote."""
+
+    slug = "no-quote"
+    display_name = "No Quote"
+
+    async def create_shipment(
+        self,
+        *,
+        sender_address: AddressInfo,
+        receiver_address: AddressInfo,
+        parcels: list[ParcelInfo],
+        **kwargs,
+    ) -> ShipmentCreateResult:
+        return {"external_id": "ext-1"}
+
+
+class TestGetQuote:
+    """BaseProvider.get_quote raises ProviderCapabilityError by default."""
+
+    async def test_default_raises_capability_error(self) -> None:
+        provider = NoQuoteProvider(shipment=DummyShipment())
+        with pytest.raises(ProviderCapabilityError):
+            await provider.get_quote(
+                service="standard",
+                parcels=[{"weight_kg": Decimal("1.0")}],
+            )
+
+    async def test_error_message_names_provider(self) -> None:
+        provider = NoQuoteProvider(shipment=DummyShipment())
+        with pytest.raises(ProviderCapabilityError) as exc_info:
+            await provider.get_quote(
+                service="standard",
+                parcels=[{"weight_kg": Decimal("1.0")}],
+            )
+        assert "NoQuoteProvider" in str(exc_info.value)
+
+
+class TestQuoteType:
+    """Quote TypedDict shape tests."""
+
+    def test_quote_shape(self) -> None:
+        quote: Quote = {
+            "provider_slug": "test",
+            "service": "standard",
+            "amount": Decimal("12.50"),
+            "currency": "PLN",
+            "valid_until": None,
+            "raw": None,
+        }
+        assert quote["amount"] == Decimal("12.50")
+        assert quote["currency"] == "PLN"
+
+    def test_quote_amount_is_decimal(self) -> None:
+        quote: Quote = {
+            "provider_slug": "test",
+            "service": "express",
+            "amount": Decimal("25.00"),
+            "currency": "EUR",
+        }
+        assert isinstance(quote["amount"], Decimal)

python_sendparcel-0.3.1/tests/test_search_points.py

@@ -0,0 +1,219 @@
+"""Tests for search_points capability."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from sendparcel.exceptions import ProviderCapabilityError
+from sendparcel.flow import ShipmentFlow
+from sendparcel.provider import BaseProvider
+from sendparcel.types import (
+    AddressInfo,
+    GeoPoint,
+    ParcelInfo,
+    PickupPoint,
+    ShipmentCreateResult,
+)
+
+
+class SearchPointsProvider(BaseProvider):
+    """Provider that supports search_points with configurable results."""
+
+    slug = "search_test"
+    display_name = "Search Test"
+    points_result: list[PickupPoint] | Exception | None = None
+
+    async def create_shipment(
+        self,
+        *,
+        sender_address: AddressInfo,
+        receiver_address: AddressInfo,
+        parcels: list[ParcelInfo],
+        **kwargs: Any,
+    ) -> ShipmentCreateResult:
+        return {"external_id": "ext-1"}
+
+    async def search_points(
+        self,
+        *,
+        query: str | None = None,
+        near: GeoPoint | None = None,
+        radius_m: int | None = None,
+        point_type: str | None = None,
+        limit: int = 20,
+        **kwargs: Any,
+    ) -> list[PickupPoint]:
+        if isinstance(self.points_result, Exception):
+            raise self.points_result
+        if self.points_result is None:
+            raise NotImplementedError("points_result not configured")
+        return self.points_result
+
+
+class NoSearchProvider(BaseProvider):
+    """Provider that does not support search_points."""
+
+    slug = "no-search"
+    display_name = "No Search"
+
+    async def create_shipment(
+        self,
+        *,
+        sender_address: AddressInfo,
+        receiver_address: AddressInfo,
+        parcels: list[ParcelInfo],
+        **kwargs: Any,
+    ) -> ShipmentCreateResult:
+        return {"external_id": "ext-1"}
+
+
+class DummyShipment:
+    id = "ship-1"
+    status = "new"
+    provider = "search_test"
+    external_id = ""
+    tracking_number = ""
+
+
+class DummyRepo:
+    async def create(self, **kwargs):
+        return DummyShipment()
+
+    async def save(self, shipment):
+        return shipment
+
+    async def update_status(self, shipment_id, status, **fields):
+        return DummyShipment()
+
+    async def update_fields(self, shipment_id, **fields):
+        return DummyShipment()
+
+    async def delete(self, shipment_id):
+        pass
+
+    async def find_by_reference(self, provider, reference_id):
+        return DummyShipment()
+
+    async def create_with_idempotency_key(
+        self, provider, status, reference_id, **kwargs
+    ):
+        return (None, DummyShipment())
+
+    def get_by_id_sync(self, shipment_id, *, for_update: bool = False):
+        return DummyShipment()
+
+    async def get_by_id(self, shipment_id, *, for_update: bool = False):
+        return DummyShipment()
+
+
+def _make_flow(
+    provider: type[BaseProvider],
+) -> tuple[ShipmentFlow, BaseProvider, DummyRepo]:
+    from sendparcel.registry import PluginRegistry
+
+    registry = PluginRegistry()
+    registry.register(provider)
+    repo = DummyRepo()
+    flow = ShipmentFlow(repository=repo, registry=registry)
+    instance = provider(shipment=repo)
+    return flow, instance, repo
+
+
+class TestSearchPointsProvider:
+    """BaseProvider.search_points raises ProviderCapabilityError by default."""
+
+    async def test_default_raises_capability_error(self) -> None:
+        provider = NoSearchProvider(shipment=DummyShipment())
+        with pytest.raises(ProviderCapabilityError):
+            await provider.search_points(query="Krakow")
+
+
+class TestSearchPointsFlow:
+    """ShipmentFlow.search_points delegates to provider."""
+
+    async def test_flow_search_points_returns_provider_results(self) -> None:
+        provider_class = SearchPointsProvider
+        provider_class.points_result = [
+            PickupPoint(
+                code="KRA010",
+                name="Krakow Main",
+                provider_slug="search_test",
+                address="ul. Glowna 1, Krakow",
+                location={"lat": 50.0647, "lng": 19.9450},
+                opening_hours=None,
+                point_type="parcel_locker",
+                raw=None,
+            )
+        ]
+        flow, _, _ = _make_flow(provider_class)
+
+        points = await flow.search_points(
+            "search_test",
+            query="Krakow",
+        )
+
+        assert len(points) == 1
+        assert points[0]["code"] == "KRA010"
+        assert points[0]["name"] == "Krakow Main"
+
+    async def test_flow_search_points_passes_params_to_provider(self) -> None:
+        provider_class = SearchPointsProvider
+        provider_class.points_result = []
+        flow, _, __ = _make_flow(provider_class)
+
+        await flow.search_points(
+            "search_test",
+            query="Warsaw",
+            near={"lat": 52.23, "lng": 21.01},
+            radius_m=5000,
+            point_type="parcel_locker",
+            limit=10,
+        )
+
+        # Provider received the call (points_result was accessed)
+        assert provider_class.points_result == []
+
+    async def test_flow_search_points_unsupported_provider_raises(self) -> None:
+        flow, _, _ = _make_flow(NoSearchProvider)
+
+        with pytest.raises(ProviderCapabilityError):
+            await flow.search_points("no-search", query="Krakow")
+
+    async def test_flow_search_points_with_proximity(self) -> None:
+        provider_class = SearchPointsProvider
+        provider_class.points_result = [
+            PickupPoint(
+                code="WAW001",
+                name="Warsaw Center",
+                provider_slug="search_test",
+                address="ul. Marszalkowska 1, Warsaw",
+                location={"lat": 52.2300, "lng": 21.0100},
+                opening_hours=None,
+                point_type="parcel_locker",
+                raw=None,
+            ),
+            PickupPoint(
+                code="WAW002",
+                name="Warsaw North",
+                provider_slug="search_test",
+                address="ul. Wawelska 2, Warsaw",
+                location={"lat": 52.2400, "lng": 21.0200},
+                opening_hours=None,
+                point_type="parcel_locker",
+                raw=None,
+            ),
+        ]
+        flow, _, _ = _make_flow(provider_class)
+
+        points = await flow.search_points(
+            "search_test",
+            near={"lat": 52.23, "lng": 21.01},
+            radius_m=5000,
+        )
+
+        assert len(points) == 2
+        # Results ordered by distance (nearest first)
+        assert points[0]["code"] == "WAW001"
+        assert points[1]["code"] == "WAW002"