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

sendparcel/providers/dummy.py

@@ -8,15 +8,10 @@ import anyio
 
 from sendparcel.enums import ConfirmationMethod, LabelFormat
 from sendparcel.exceptions import InvalidCallbackError
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -24,13 +19,7 @@ from sendparcel.types import (
 )
 
 
-class DummyProvider(
-    BaseProvider,
-    LabelProvider,
-    PushCallbackProvider,
-    PullStatusProvider,
-    CancellableProvider,
-):
+class DummyProvider(BaseProvider):
     """Reference provider for local, development, and test usage."""
 
     slug: ClassVar[str] = "dummy"
@@ -66,19 +55,17 @@ class DummyProvider(
         await self._simulate_latency()
         return LabelInfo(format=LabelFormat.PDF, url=self._label_url())
 
-    async def verify_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
-    ) -> None:
+    async def verify_callback(self, ctx: CallbackContext) -> None:
         expected = self.get_setting("callback_token", "dummy-token")
-        provided = headers.get("x-dummy-token", "")
+        provided = ctx.headers.get("x-dummy-token", "")
         if provided != expected:
             raise InvalidCallbackError("BAD TOKEN")
 
     async def handle_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
+        self, ctx: CallbackContext
     ) -> ShipmentUpdateResult:
         await self._simulate_latency()
-        status_value = data.get("status")
+        status_value = ctx.payload.get("status")
         if not status_value:
             return ShipmentUpdateResult()
         return ShipmentUpdateResult(status=str(status_value))

sendparcel/registry.py

@@ -62,6 +62,15 @@ class PluginRegistry:
             except KeyError as exc:
                 raise ProviderNotFoundError(slug) from exc
 
+    def slugs(self) -> list[str]:
+        """Get all registered provider slugs.
+
+        Thread-safe.
+        """
+        self._ensure_discovered()
+        with self._lock:
+            return list(self._providers)
+
     def get_choices(self) -> list[tuple[str, str]]:
         """Get provider slug/display pairs for user-facing selection.
 

sendparcel/types.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
 from dataclasses import dataclass
+from datetime import datetime
 from decimal import Decimal
-from typing import TypedDict
+from enum import StrEnum
+from typing import Any, TypedDict
 
 from sendparcel.enums import LabelFormat
 from sendparcel.protocols import Shipment
@@ -81,9 +85,6 @@ class ShipmentUpdateResult(TypedDict, total=False):
     tracking_events: list[TrackingEvent]
 
 
-ShipmentStatusResponse = ShipmentUpdateResult
-
-
 @dataclass(frozen=True, slots=True)
 class CreateShipmentOutcome:
     """Flow result for shipment creation."""
@@ -106,3 +107,106 @@ class ShipmentUpdateOutcome:
 
     shipment: Shipment
     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.
+
+    Framework layers build this in one place. Core operates on it.
+    The retry store persists this as a single blob.
+
+    The ``dedup_hash`` is computed from the payload alone (not headers
+    or source_ip) so that legitimate re-submissions of the same callback
+    data are deduplicated regardless of transport metadata.
+    """
+
+    shipment_id: str
+    payload: dict[str, Any]
+    headers: dict[str, str]
+    source_ip: str
+    raw_body: bytes
+    provider_slug: str = ""
+
+    @property
+    def dedup_hash(self) -> str:
+        """Deterministic SHA-256 hash of the payload for dedup checks."""
+        raw = json.dumps(self.payload, sort_keys=True, default=str).encode(
+            "utf-8"
+        )
+        return hashlib.sha256(raw).hexdigest()

python_sendparcel-0.2.0.dist-info/RECORD

@@ -1,19 +0,0 @@
-sendparcel/__init__.py,sha256=aHh6hwMkQVrICkswatKnt3Aru-v3kQI0PotD0M3QocQ,1612
-sendparcel/batch.py,sha256=wilO2jPbwlmLowYbhfhNZV17VPX6K_Lf9aHKxWUgbcQ,9400
-sendparcel/enums.py,sha256=e1UM9ka5zWJg4naMCoVeUrIy_PVPPEYHOBh6XiXaW4Q,687
-sendparcel/exceptions.py,sha256=zC5_o9oQfNuOBKaiw5csaHAJmhYsZc3WVbOaoq7s1W0,1437
-sendparcel/flow.py,sha256=REP0i1W2YU09bLVBZWJDUf4mkQ4An4yTZOKMPsfGXL8,11258
-sendparcel/fsm.py,sha256=7Oqccbn2U56htTJLQEidNhZn_0TVtR-js_6OHkTu0zE,3182
-sendparcel/logging.py,sha256=SY7bTtXyPDM-tYCXHRV99YFwK8lHDXpfgB8IN8tOrH0,4843
-sendparcel/protocols.py,sha256=7YX2KTOEG5Nje6bzibmIODFiTX7tgqb6I3WYgx9uVS4,2344
-sendparcel/provider.py,sha256=6f6Z3hmLNrN2t-pulVAFEPrZnNttX1kmK6ATCnqdZD4,2690
-sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sendparcel/registry.py,sha256=xLDgux5kkp2n5DHfLwOD6mx7yBfMdOyD4QHKUcxJpnw,3575
-sendparcel/types.py,sha256=afPuER1CslkvcTMMogY0EVYrTjUsA36gPxVQguYtIBg,2201
-sendparcel/validators.py,sha256=i_y-edT1hgS_2HeRdARlFaQXiL9sYAzWVsjYPVBqRDc,589
-sendparcel/providers/__init__.py,sha256=ff82dvrWuPS-UIGF5AoX_fgpcYZaGu2k6q2yrxMZacI,192
-sendparcel/providers/dummy.py,sha256=sbXDtPel3DEH_FIN9_gX2xXBLEqZ7Pto3CP_JMcsaEM,3102
-python_sendparcel-0.2.0.dist-info/METADATA,sha256=fozQ4Jz1PhvcQAEnl1zHHb2DTTIXNvhJdKDGjWBPnzE,6429
-python_sendparcel-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_sendparcel-0.2.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
-python_sendparcel-0.2.0.dist-info/RECORD,,

sendparcel/validators.py

@@ -1,21 +0,0 @@
-"""Pluggable validation system.
-
-Validators are callables that receive a data dict, optionally
-modify it, and return it. Raise an exception to reject.
-"""
-
-from collections.abc import Callable
-from typing import Any
-
-
-def run_validators(
-    data: dict[str, Any], validators: list[Callable[..., Any]] | None = None
-) -> dict[str, Any]:
-    """Run a chain of validators on data.
-
-    Each validator receives the data dict and must return it
-    (possibly modified). Raise an exception to reject.
-    """
-    for validator in validators or []:
-        data = validator(data)
-    return data