python-sendparcel 0.1.0__py3-none-any.whl

python_sendparcel-0.1.0.dist-info/METADATA

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: python-sendparcel
+Version: 0.1.0
+Summary: Framework-agnostic parcel shipping core for Python.
+Project-URL: Homepage, https://github.com/sendparcel/python-sendparcel
+Project-URL: Documentation, https://python-sendparcel.readthedocs.io/
+Project-URL: Repository, https://github.com/sendparcel/python-sendparcel
+Project-URL: Changelog, https://github.com/sendparcel/python-sendparcel/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/sendparcel/python-sendparcel/issues
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+License-File: LICENSE
+Keywords: delivery,logistics,parcel,sendparcel,shipping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: transitions>=0.9.0
+Provides-Extra: all
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'all'
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'all'
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pre-commit-hooks>=6.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: ty>=0.0.16; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'django'
+Provides-Extra: dummy
+Provides-Extra: fastapi
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'fastapi'
+Provides-Extra: frameworks
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'frameworks'
+Provides-Extra: litestar
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'litestar'
+Provides-Extra: providers
+Description-Content-Type: text/markdown
+
+# python-sendparcel
+
+[![PyPI](https://img.shields.io/pypi/v/python-sendparcel.svg)](https://pypi.org/project/python-sendparcel/)
+[![Python Version](https://img.shields.io/pypi/pyversions/python-sendparcel.svg)](https://pypi.org/project/python-sendparcel/)
+[![License](https://img.shields.io/pypi/l/python-sendparcel.svg)](https://pypi.org/project/python-sendparcel/)
+
+Framework-agnostic parcel shipping core for Python.
+
+---
+
+> **Alpha notice** — This project is at version **0.1.0**. The public API
+> may change between minor releases until 1.0 is reached. Pin your
+> dependency accordingly.
+
+## Features
+
+- **Provider plugin system** — register providers via entry points or manually; auto-discovery at first use.
+- **Shipment domain types** — `AddressInfo`, `ParcelInfo`, `LabelInfo`, `ShipmentCreateResult`, `ShipmentStatusResponse`, and `TrackingEvent` as strict TypedDicts.
+- **Finite state machine** — 9-state `ShipmentStatus` enum (`NEW` → `CREATED` → `LABEL_READY` → `IN_TRANSIT` → `OUT_FOR_DELIVERY` → `DELIVERED`, plus `CANCELLED`, `FAILED`, `RETURNED`) with guarded transitions powered by [transitions](https://github.com/pytransitions/transitions).
+- **ShipmentFlow orchestrator** — framework-agnostic async workflow for creating shipments, fetching labels, handling callbacks, polling status, and cancelling.
+- **BaseProvider ABC** — define your own provider by subclassing a single class with well-defined async methods.
+- **Built-in DummyProvider** — deterministic reference provider for testing and local development.
+- **Pluggable validators** — attach validator callables to `ShipmentFlow` for global or per-operation validation.
+- **Runtime protocols** — `Order`, `Shipment`, and `ShipmentRepository` are `@runtime_checkable` protocols; bring your own models and persistence.
+- **Async-first** — the entire runtime is async, powered by [anyio](https://anyio.readthedocs.io/).
+
+## Installation
+
+### With pip
+
+```bash
+pip install python-sendparcel
+```
+
+### With uv
+
+```bash
+uv add python-sendparcel
+```
+
+### Framework adapters
+
+Install the adapter for your web framework:
+
+```bash
+pip install python-sendparcel[django]    # Django integration
+pip install python-sendparcel[fastapi]   # FastAPI integration
+pip install python-sendparcel[litestar]  # Litestar integration
+pip install python-sendparcel[frameworks]  # all framework adapters
+pip install python-sendparcel[all]       # everything
+```
+
+### Extras reference
+
+| Extra | Installs |
+|---|---|
+| `dummy` | Built-in dummy provider (no extra package) |
+| `django` | `django-sendparcel` |
+| `fastapi` | `fastapi-sendparcel` |
+| `litestar` | `litestar-sendparcel` |
+| `providers` | Built-in providers (currently `dummy`) |
+| `frameworks` | All framework adapters |
+| `all` | Framework adapters |
+
+## Quick Start
+
+python-sendparcel is framework-agnostic. You provide implementations of three
+protocols — `Order`, `Shipment`, and `ShipmentRepository` — and the library
+handles orchestration, state transitions, and provider communication.
+
+### 1. Implement the Order protocol
+
+```python
+from decimal import Decimal
+from dataclasses import dataclass, field
+
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@dataclass
+class MyOrder:
+    """Satisfies the sendparcel Order protocol."""
+
+    sender: AddressInfo
+    receiver: AddressInfo
+    parcels: list[ParcelInfo] = field(default_factory=list)
+
+    def get_total_weight(self) -> Decimal:
+        return sum(p["weight_kg"] for p in self.parcels)
+
+    def get_parcels(self) -> list[ParcelInfo]:
+        return self.parcels
+
+    def get_sender_address(self) -> AddressInfo:
+        return self.sender
+
+    def get_receiver_address(self) -> AddressInfo:
+        return self.receiver
+```
+
+### 2. Implement the Shipment and ShipmentRepository protocols
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass
+class MyShipment:
+    """Satisfies the sendparcel Shipment protocol."""
+
+    id: str
+    order: MyOrder
+    status: str = ""
+    provider: str = ""
+    external_id: str = ""
+    tracking_number: str = ""
+    label_url: str = ""
+
+
+class InMemoryRepository:
+    """Minimal in-memory ShipmentRepository for demonstration."""
+
+    def __init__(self):
+        self._store: dict[str, MyShipment] = {}
+        self._counter = 0
+
+    async def get_by_id(self, shipment_id: str) -> MyShipment:
+        return self._store[shipment_id]
+
+    async def create(self, **kwargs) -> MyShipment:
+        self._counter += 1
+        shipment_id = str(self._counter)
+        shipment = MyShipment(
+            id=shipment_id,
+            order=kwargs["order"],
+            status=kwargs.get("status", ""),
+            provider=kwargs.get("provider", ""),
+        )
+        self._store[shipment_id] = shipment
+        return shipment
+
+    async def save(self, shipment: MyShipment) -> MyShipment:
+        self._store[shipment.id] = shipment
+        return shipment
+
+    async def update_status(
+        self, shipment_id: str, status: str, **fields
+    ) -> MyShipment:
+        shipment = self._store[shipment_id]
+        shipment.status = status
+        return shipment
+```
+
+### 3. Create a shipment with ShipmentFlow
+
+```python
+import anyio
+
+from sendparcel import ShipmentFlow, ShipmentStatus
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+async def main():
+    repo = InMemoryRepository()
+    flow = ShipmentFlow(repository=repo)
+
+    order = MyOrder(
+        sender=AddressInfo(
+            name="Sender Co.",
+            line1="ul. Marszalkowska 1",
+            city="Warszawa",
+            postal_code="00-001",
+            country_code="PL",
+        ),
+        receiver=AddressInfo(
+            name="Jan Kowalski",
+            line1="ul. Dluga 10",
+            city="Gdansk",
+            postal_code="80-001",
+            country_code="PL",
+        ),
+        parcels=[ParcelInfo(weight_kg=Decimal("2.5"))],
+    )
+
+    # Create shipment using the built-in dummy provider
+    shipment = await flow.create_shipment(order, provider_slug="dummy")
+    print(shipment.status)           # "created" or "label_ready"
+    print(shipment.external_id)      # "dummy-1"
+    print(shipment.tracking_number)  # "DUMMY-1"
+
+
+anyio.run(main)
+```
+
+## Architecture
+
+python-sendparcel is organized into focused modules:
+
+```
+sendparcel/
+├── __init__.py          # Public API surface
+├── enums.py             # ShipmentStatus, ConfirmationMethod
+├── types.py             # TypedDict definitions (AddressInfo, ParcelInfo, …)
+├── protocols.py         # Order, Shipment, ShipmentRepository protocols
+├── provider.py          # BaseProvider ABC
+├── registry.py          # PluginRegistry with entry-point discovery
+├── flow.py              # ShipmentFlow orchestrator
+├── fsm.py               # State machine transitions (pytransitions)
+├── validators.py        # Pluggable validation chain
+├── exceptions.py        # Exception hierarchy
+└── providers/
+    ├── __init__.py      # Built-in provider list
+    └── dummy.py         # DummyProvider reference implementation
+```
+
+### Key components
+
+| Component | Module | Description |
+|---|---|---|
+| `ShipmentFlow` | `flow.py` | Async orchestrator — creates shipments, fetches labels, handles callbacks, polls status, cancels. |
+| `BaseProvider` | `provider.py` | Abstract base class that all shipping providers must subclass. |
+| `PluginRegistry` | `registry.py` | Discovers providers from `sendparcel.providers` entry points and built-ins. Global `registry` singleton. |
+| `ShipmentStatus` | `enums.py` | 9-state `StrEnum` representing the shipment lifecycle. |
+| Domain types | `types.py` | `AddressInfo`, `ParcelInfo`, `LabelInfo`, `ShipmentCreateResult`, `ShipmentStatusResponse`, `TrackingEvent`. |
+| Protocols | `protocols.py` | `Order`, `Shipment`, `ShipmentRepository` — all `@runtime_checkable`. |
+| FSM | `fsm.py` | Transition definitions with guards (e.g. `label_url` required before `confirm_label`). |
+| Validators | `validators.py` | Chain of callables invoked before provider operations. |
+
+### Shipment state machine
+
+```
+                                                    mark_in_transit
+                                              ┌────────────────────┐
+                                              │                    ▼
+NEW ──confirm_created──▸ CREATED ──confirm_label──▸ LABEL_READY   IN_TRANSIT ──mark_out_for_delivery──▸ OUT_FOR_DELIVERY
+ │                         │                          │            │  │                                    │  │
+ │                         │                          │            │  ├── mark_delivered ─────────────────▸│  │
+ │                         │                          │            │  │                                    │  │
+ │                         │                          │            │  │       mark_delivered               │  │
+ │                         │                          │            │  │  ┌────────────────────────────────-─┘  │
+ │                         │                          │            │  │  ▼                                    │
+ │                         │                          │            │  │ DELIVERED                              │
+ │                         │                          │            │  │  │                                    │
+ │                         │                          │            │  │  └── mark_returned ──▸ RETURNED ◂─────┤
+ │                         │                          │            │  │                          ▴            │
+ │                         │                          │            │  └── mark_returned ─────────┘            │
+ │                         │                          │            │                                          │
+ └──────── cancel ─────────┴────── cancel ────────────┴──▸ CANCELLED                                         │
+                                                                                                             │
+ Any of {NEW, CREATED, LABEL_READY, IN_TRANSIT, OUT_FOR_DELIVERY} ──fail──▸ FAILED                           │
+```
+
+Guards enforce data integrity:
+- `confirm_label` requires `label_url` to be set on the shipment.
+- `mark_in_transit` requires `tracking_number` to be set on the shipment.
+
+## Provider Authoring
+
+Create a provider by subclassing `BaseProvider` and implementing `create_shipment`:
+
+```python
+from typing import ClassVar
+
+from sendparcel.provider import BaseProvider
+from sendparcel.types import ShipmentCreateResult
+
+
+class MyCarrierProvider(BaseProvider):
+    slug: ClassVar[str] = "mycarrier"
+    display_name: ClassVar[str] = "My Carrier"
+    supported_countries: ClassVar[list[str]] = ["PL", "DE"]
+    supported_services: ClassVar[list[str]] = ["standard"]
+
+    async def create_shipment(self, **kwargs) -> ShipmentCreateResult:
+        # Call your carrier's API here
+        api_key = self.get_setting("api_key")
+        sender = self.shipment.order.get_sender_address()
+        receiver = self.shipment.order.get_receiver_address()
+        # ... HTTP call to carrier API ...
+        return ShipmentCreateResult(
+            external_id="carrier-12345",
+            tracking_number="TRACK-12345",
+        )
+```
+
+### Entry-point registration
+
+Declare your provider in `pyproject.toml` so it is auto-discovered:
+
+```toml
+[project.entry-points."sendparcel.providers"]
+mycarrier = "mycarrier_sendparcel.provider:MyCarrierProvider"
+```
+
+### Manual registration
+
+```python
+from sendparcel import registry
+
+registry.register(MyCarrierProvider)
+```
+
+### Provider configuration
+
+Pass per-provider settings through `ShipmentFlow`:
+
+```python
+flow = ShipmentFlow(
+    repository=repo,
+    config={
+        "mycarrier": {
+            "api_key": "sk_live_...",
+            "sandbox": True,
+        },
+    },
+)
+```
+
+Settings are accessible inside the provider via `self.get_setting("api_key")`.
+
+### Optional methods
+
+Beyond the required `create_shipment`, providers can override:
+
+| Method | Purpose |
+|---|---|
+| `create_label(**kwargs)` | Generate or fetch a shipping label. |
+| `verify_callback(data, headers, **kwargs)` | Validate webhook authenticity. |
+| `handle_callback(data, headers, **kwargs)` | Apply webhook status updates. |
+| `fetch_shipment_status(**kwargs)` | Poll current shipment status. |
+| `cancel_shipment(**kwargs)` | Cancel a shipment. |
+
+### Class-level attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `slug` | `str` | Unique provider identifier. |
+| `display_name` | `str` | Human-readable name. |
+| `supported_countries` | `list[str]` | ISO country codes. |
+| `supported_services` | `list[str]` | Service level identifiers. |
+| `confirmation_method` | `ConfirmationMethod` | `PUSH` (webhook) or `PULL` (polling). Default: `PUSH`. |
+| `user_selectable` | `bool` | Whether this provider appears in `registry.get_choices()`. Default: `True`. |
+
+## Ecosystem
+
+python-sendparcel is the core library. Framework-specific integrations are
+provided by separate packages:
+
+| Package | Framework | Repository |
+|---|---|---|
+| [django-sendparcel](https://github.com/sendparcel/django-sendparcel) | Django | `sendparcel/django-sendparcel` |
+| [fastapi-sendparcel](https://github.com/sendparcel/fastapi-sendparcel) | FastAPI | `sendparcel/fastapi-sendparcel` |
+| [litestar-sendparcel](https://github.com/sendparcel/litestar-sendparcel) | Litestar | `sendparcel/litestar-sendparcel` |
+
+Each wrapper provides framework-native models, views/routes, and repository
+implementations so you don't have to write the boilerplate shown in the Quick
+Start above.
+
+## Supported Versions
+
+| Python | Status |
+|---|---|
+| 3.12+ | Supported |
+| 3.13 | Supported |
+| < 3.12 | Not supported |
+
+### Core dependencies
+
+| Package | Minimum version |
+|---|---|
+| `transitions` | 0.9.0 |
+| `httpx` | 0.27.0 |
+| `anyio` | 4.0 |
+
+## Running Tests
+
+The test suite uses **pytest** with **pytest-asyncio**.
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run the full test suite
+uv run pytest
+
+# With coverage
+uv run pytest --cov=sendparcel --cov-report=term-missing
+```
+
+## Credits
+
+- **Author:** Dominik Kozaczko ([dominik@kozaczko.info](mailto:dominik@kozaczko.info))
+- Inspired by the [django-getpaid](https://github.com/django-getpaid/django-getpaid) architecture and plugin model.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

python_sendparcel-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sendparcel/__init__.py,sha256=WACW8aHx1NhIjfnyB9zgl4TtF__74x-yzwQSzl-yDT4,710
+sendparcel/enums.py,sha256=HUdeuKIt3s2Gzh6loXPvNKJXqGm9LSfuHRwVmhPtcVM,513
+sendparcel/exceptions.py,sha256=9nfRcWxHh9YTEmLSUgoUH22qmHP9-EIgHVAXQiox80k,570
+sendparcel/flow.py,sha256=zKUKiFthYbJWgVR863acY1ZkJq4FWB6xff8SV6mb_dc,6374
+sendparcel/fsm.py,sha256=qdQzJVupvjamZ8nvixaqO5XEvovOPdC6GwbudeJf9n8,3662
+sendparcel/protocols.py,sha256=XFsodkNXHENeLEonlDioq-R5r0JRzf7L58V3DJ9jYRw,1094
+sendparcel/provider.py,sha256=eKiot1b3SOgaqMJzKjSTgT6CbX9xNEvZSwZn02xha4g,2063
+sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendparcel/registry.py,sha256=s3uhw0ja9BoFKnS3c_W-oBXGMlZY7mmQRiFxs3wJ88o,2342
+sendparcel/types.py,sha256=R2Z90fj3gzG3Uyu5W2eOHFMcA6MudTh94POw7GgQZYo,1522
+sendparcel/validators.py,sha256=0LRSM2cqTF3f8CImP2mt8fXPGeQSD4tIpMxxhfk0YhA,536
+sendparcel/providers/__init__.py,sha256=ff82dvrWuPS-UIGF5AoX_fgpcYZaGu2k6q2yrxMZacI,192
+sendparcel/providers/dummy.py,sha256=miMzRL8EXotQEV0_Moa-rH6rRQiA0fM57O8a0kS5iP4,2715
+python_sendparcel-0.1.0.dist-info/METADATA,sha256=CziXBxiHU8TXzuMaCVo6x9jX9E6imk_O435Gm4anwJk,17156
+python_sendparcel-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_sendparcel-0.1.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
+python_sendparcel-0.1.0.dist-info/RECORD,,

python_sendparcel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_sendparcel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,10 @@
+
+MIT License
+
+Copyright (c) 2025, Dominik Kozaczko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sendparcel/__init__.py

@@ -0,0 +1,29 @@
+"""sendparcel core package."""
+
+__version__ = "0.1.0"
+
+from sendparcel.enums import ConfirmationMethod, ShipmentStatus
+from sendparcel.exceptions import (
+    CommunicationError,
+    InvalidCallbackError,
+    InvalidTransitionError,
+    SendParcelException,
+)
+from sendparcel.flow import ShipmentFlow
+from sendparcel.provider import BaseProvider
+from sendparcel.providers.dummy import DummyProvider
+from sendparcel.registry import registry
+
+__all__ = [
+    "BaseProvider",
+    "CommunicationError",
+    "ConfirmationMethod",
+    "DummyProvider",
+    "InvalidCallbackError",
+    "InvalidTransitionError",
+    "SendParcelException",
+    "ShipmentFlow",
+    "ShipmentStatus",
+    "__version__",
+    "registry",
+]

sendparcel/enums.py

@@ -0,0 +1,24 @@
+"""Shipment processing enums."""
+
+from enum import StrEnum
+
+
+class ShipmentStatus(StrEnum):
+    """Shipment lifecycle status."""
+
+    NEW = "new"
+    CREATED = "created"
+    LABEL_READY = "label_ready"
+    IN_TRANSIT = "in_transit"
+    OUT_FOR_DELIVERY = "out_for_delivery"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+    RETURNED = "returned"
+
+
+class ConfirmationMethod(StrEnum):
+    """How the provider confirms shipment status updates."""
+
+    PUSH = "PUSH"
+    PULL = "PULL"

sendparcel/exceptions.py

@@ -0,0 +1,21 @@
+"""Exception hierarchy for sendparcel."""
+
+
+class SendParcelException(Exception):
+    """Base exception for sendparcel."""
+
+    def __init__(self, message: str = "", context: dict | None = None) -> None:
+        super().__init__(message)
+        self.context = context or {}
+
+
+class CommunicationError(SendParcelException):
+    """Provider communication failed."""
+
+
+class InvalidCallbackError(SendParcelException):
+    """Webhook callback validation failed."""
+
+
+class InvalidTransitionError(SendParcelException):
+    """Invalid shipment state transition requested."""

sendparcel/flow.py

@@ -0,0 +1,164 @@
+"""Shipment flow orchestrator."""
+
+import httpx
+
+from sendparcel.enums import ShipmentStatus
+from sendparcel.exceptions import (
+    CommunicationError,
+    InvalidTransitionError,
+    SendParcelException,
+)
+from sendparcel.fsm import (
+    STATUS_TO_CALLBACK,
+    create_shipment_machine,
+)
+from sendparcel.protocols import Order, Shipment, ShipmentRepository
+from sendparcel.registry import registry
+from sendparcel.validators import run_validators
+
+
+class ShipmentFlow:
+    """Framework-agnostic shipment orchestration."""
+
+    def __init__(
+        self,
+        repository: ShipmentRepository,
+        config: dict | None = None,
+        validators: list | None = None,
+    ) -> None:
+        self.repository = repository
+        self.config = config or {}
+        self.validators = validators or []
+
+    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)
+        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."""
+        run_validators({"shipment": shipment}, validators=self.validators)
+        create_shipment_machine(shipment)
+        provider = self._get_provider(shipment)
+        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)
+
+    async def handle_callback(
+        self,
+        shipment: Shipment,
+        data: dict,
+        headers: dict,
+        **kwargs,
+    ) -> Shipment:
+        """Verify and apply provider callback."""
+        provider = self._get_provider(shipment)
+        create_shipment_machine(shipment)
+        await self._call_provider(
+            provider.verify_callback(data, headers, **kwargs)
+        )
+        await self._call_provider(
+            provider.handle_callback(data, headers, **kwargs)
+        )
+        return await self.repository.save(shipment)
+
+    async def fetch_and_update_status(self, shipment: Shipment) -> Shipment:
+        """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:
+        """Cancel shipment via provider and persist state."""
+        provider = self._get_provider(shipment)
+        create_shipment_machine(shipment)
+        cancelled = await self._call_provider(
+            provider.cancel_shipment(**kwargs)
+        )
+        if cancelled:
+            self._trigger(shipment, "cancel")
+            await self.repository.save(shipment)
+        return cancelled
+
+    def _get_provider(self, shipment: Shipment):
+        provider_class = 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."""
+        try:
+            return await coro
+        except SendParcelException:
+            raise
+        except httpx.HTTPError as exc:
+            raise CommunicationError(
+                str(exc),
+                context={"original_error": type(exc).__name__},
+            ) from exc
+        except Exception as 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

@@ -0,0 +1,131 @@
+"""Shipment state machine definitions."""
+
+from transitions import Machine
+from transitions.core import MachineError
+
+from sendparcel.enums import ShipmentStatus
+
+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": [
+            ShipmentStatus.IN_TRANSIT,
+            ShipmentStatus.OUT_FOR_DELIVERY,
+        ],
+        "dest": ShipmentStatus.DELIVERED,
+    },
+    {
+        "trigger": "mark_returned",
+        "source": [
+            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.OUT_FOR_DELIVERY,
+        ],
+        "dest": 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 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,
+    )

sendparcel/protocols.py

@@ -0,0 +1,41 @@
+"""Framework integration protocols."""
+
+from decimal import Decimal
+from typing import Protocol, runtime_checkable
+
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@runtime_checkable
+class Order(Protocol):
+    """Order shape expected by sendparcel core."""
+
+    def get_total_weight(self) -> Decimal: ...
+    def get_parcels(self) -> list[ParcelInfo]: ...
+    def get_sender_address(self) -> AddressInfo: ...
+    def get_receiver_address(self) -> AddressInfo: ...
+
+
+@runtime_checkable
+class Shipment(Protocol):
+    """Shipment shape expected by sendparcel core."""
+
+    id: str
+    order: Order
+    status: str
+    provider: str
+    external_id: str
+    tracking_number: str
+    label_url: str
+
+
+@runtime_checkable
+class ShipmentRepository(Protocol):
+    """Persistence abstraction for adapters."""
+
+    async def get_by_id(self, shipment_id: str) -> Shipment: ...
+    async def create(self, **kwargs) -> Shipment: ...
+    async def save(self, shipment: Shipment) -> Shipment: ...
+    async def update_status(
+        self, shipment_id: str, status: str, **fields
+    ) -> Shipment: ...

sendparcel/provider.py

@@ -0,0 +1,63 @@
+"""Base provider abstraction."""
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from sendparcel.enums import ConfirmationMethod
+from sendparcel.protocols import Shipment
+from sendparcel.types import (
+    LabelInfo,
+    ShipmentCreateResult,
+    ShipmentStatusResponse,
+)
+
+
+class BaseProvider(ABC):
+    """Base class for parcel delivery providers."""
+
+    slug: ClassVar[str] = ""
+    display_name: ClassVar[str] = ""
+    supported_countries: ClassVar[list[str]] = []
+    supported_services: ClassVar[list[str]] = []
+    confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.PUSH
+    user_selectable: ClassVar[bool] = True
+
+    def __init__(self, shipment: Shipment, config: dict | None = None) -> None:
+        self.shipment = shipment
+        self.config = config or {}
+
+    def get_setting(self, name: str, default=None):
+        """Read provider setting from config."""
+        return self.config.get(name, default)
+
+    @abstractmethod
+    async def create_shipment(self, **kwargs) -> ShipmentCreateResult:
+        """Create shipment in provider API."""
+
+    async def create_label(self, **kwargs) -> LabelInfo:
+        """Create/fetch label for shipment."""
+        raise NotImplementedError
+
+    async def verify_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        """Verify callback authenticity.
+
+        Providers that accept callbacks MUST override this to validate
+        signatures/tokens. Raise InvalidCallbackError to reject.
+        """
+        raise NotImplementedError
+
+    async def handle_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        """Apply callback updates to shipment."""
+        raise NotImplementedError
+
+    async def fetch_shipment_status(self, **kwargs) -> ShipmentStatusResponse:
+        """Fetch latest shipment status from provider."""
+        raise NotImplementedError
+
+    async def cancel_shipment(self, **kwargs) -> bool:
+        """Cancel shipment if provider supports cancellation."""
+        raise NotImplementedError

sendparcel/providers/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in providers shipped with sendparcel."""
+
+from sendparcel.providers.dummy import DummyProvider
+
+BUILTIN_PROVIDERS = (DummyProvider,)
+
+__all__ = ["BUILTIN_PROVIDERS", "DummyProvider"]

sendparcel/providers/dummy.py

@@ -0,0 +1,77 @@
+"""Deterministic built-in dummy provider implementation."""
+
+from typing import ClassVar
+
+import anyio
+
+from sendparcel.exceptions import InvalidCallbackError
+from sendparcel.fsm import STATUS_TO_CALLBACK
+from sendparcel.provider import BaseProvider
+from sendparcel.types import (
+    LabelInfo,
+    ShipmentCreateResult,
+    ShipmentStatusResponse,
+)
+
+
+class DummyProvider(BaseProvider):
+    """Reference provider for local/dev/testing usage."""
+
+    slug: ClassVar[str] = "dummy"
+    display_name: ClassVar[str] = "Dummy"
+    supported_countries: ClassVar[list[str]] = ["PL", "DE", "US"]
+    supported_services: ClassVar[list[str]] = ["standard", "express"]
+
+    def _label_url(self) -> str:
+        base = self.get_setting("label_base_url", "https://dummy.local/labels")
+        return f"{str(base).rstrip('/')}/{self.shipment.id}.pdf"
+
+    async def _simulate_latency(self) -> None:
+        delay = float(self.get_setting("latency_seconds", 0.0))
+        await anyio.sleep(delay)
+
+    async def create_shipment(self, **kwargs) -> ShipmentCreateResult:
+        await self._simulate_latency()
+        shipment_id = str(self.shipment.id)
+        return ShipmentCreateResult(
+            external_id=f"dummy-{shipment_id}",
+            tracking_number=f"DUMMY-{shipment_id.upper()}",
+        )
+
+    async def create_label(self, **kwargs) -> LabelInfo:
+        await self._simulate_latency()
+        return LabelInfo(format="PDF", url=self._label_url())
+
+    async def verify_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        expected = self.get_setting("callback_token", "dummy-token")
+        provided = headers.get("x-dummy-token", "")
+        if provided != expected:
+            raise InvalidCallbackError("BAD TOKEN")
+
+    async def handle_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        await self._simulate_latency()
+        status_value = data.get("status")
+        if not status_value:
+            return
+
+        callback = STATUS_TO_CALLBACK.get(str(status_value), str(status_value))
+        trigger = getattr(self.shipment, callback, None)
+        may_trigger = getattr(self.shipment, "may_trigger", None)
+        if trigger is None or may_trigger is None:
+            return
+        if may_trigger(callback):
+            trigger()
+
+    async def fetch_shipment_status(self, **kwargs) -> ShipmentStatusResponse:
+        await self._simulate_latency()
+        return ShipmentStatusResponse(
+            status=self.get_setting("status_override", self.shipment.status),
+        )
+
+    async def cancel_shipment(self, **kwargs) -> bool:
+        await self._simulate_latency()
+        return bool(self.get_setting("cancel_success", True))

sendparcel/registry.py

@@ -0,0 +1,70 @@
+"""Provider plugin registry."""
+
+from importlib.metadata import entry_points
+
+from sendparcel.provider import BaseProvider
+
+ENTRY_POINT_GROUP = "sendparcel.providers"
+
+
+class PluginRegistry:
+    """Discover and store provider classes."""
+
+    def __init__(self) -> None:
+        self._providers: dict[str, type[BaseProvider]] = {}
+        self._discovered = False
+
+    def discover(self) -> None:
+        """Load providers from entry points."""
+        from sendparcel.providers import BUILTIN_PROVIDERS
+
+        for provider_class in BUILTIN_PROVIDERS:
+            self._register_provider(provider_class)
+        eps = entry_points(group=ENTRY_POINT_GROUP)
+        for ep in eps:
+            provider_class = ep.load()
+            if isinstance(provider_class, type) and issubclass(
+                provider_class, BaseProvider
+            ):
+                self._register_provider(provider_class)
+        self._discovered = True
+
+    def register(self, provider_class: type[BaseProvider]) -> None:
+        """Register provider manually."""
+        self._register_provider(provider_class)
+
+    def unregister(self, slug: str) -> None:
+        """Unregister provider by slug."""
+        self._providers.pop(slug, None)
+
+    def get_by_slug(self, slug: str) -> type[BaseProvider]:
+        """Get provider class by slug."""
+        self._ensure_discovered()
+        return self._providers[slug]
+
+    def get_choices(self) -> list[tuple[str, str]]:
+        """Get provider slug/display pairs for user-facing selection."""
+        self._ensure_discovered()
+        return [
+            (p.slug, p.display_name)
+            for p in self._providers.values()
+            if p.user_selectable
+        ]
+
+    def _ensure_discovered(self) -> None:
+        if not self._discovered:
+            self.discover()
+
+    def _register_provider(self, provider_class: type[BaseProvider]) -> None:
+        slug = provider_class.slug
+        existing = self._providers.get(slug)
+        if existing is not None and existing is not provider_class:
+            raise ValueError(
+                f"Duplicate provider slug {slug!r}: "
+                f"{existing.__module__}.{existing.__name__} and "
+                f"{provider_class.__module__}.{provider_class.__name__}"
+            )
+        self._providers[slug] = provider_class
+
+
+registry = PluginRegistry()

sendparcel/types.py

@@ -0,0 +1,80 @@
+"""Shared type definitions."""
+
+from decimal import Decimal
+from typing import TypedDict
+
+
+class _AddressInfoRequired(TypedDict):
+    """Required address fields."""
+
+    name: str
+    line1: str
+    city: str
+    postal_code: str
+    country_code: str
+
+
+class AddressInfo(_AddressInfoRequired, total=False):
+    """Address payload used by providers."""
+
+    company: str
+    line2: str
+    state: str
+    phone: str
+    email: str
+
+
+class _ParcelInfoRequired(TypedDict):
+    """Required parcel fields."""
+
+    weight_kg: Decimal
+
+
+class ParcelInfo(_ParcelInfoRequired, total=False):
+    """Parcel dimensions and weight."""
+
+    length_cm: Decimal
+    width_cm: Decimal
+    height_cm: Decimal
+
+
+class _LabelInfoRequired(TypedDict):
+    """Required label fields."""
+
+    format: str
+
+
+class LabelInfo(_LabelInfoRequired, total=False):
+    """Shipping label metadata."""
+
+    url: str
+    content_base64: str
+
+
+class TrackingEvent(TypedDict, total=False):
+    """Single tracking timeline event."""
+
+    code: str
+    description: str
+    occurred_at: str
+    location: str
+
+
+class _ShipmentCreateResultRequired(TypedDict):
+    """Required result fields."""
+
+    external_id: str
+
+
+class ShipmentCreateResult(_ShipmentCreateResultRequired, total=False):
+    """Provider response for create_shipment."""
+
+    tracking_number: str
+    label: LabelInfo
+
+
+class ShipmentStatusResponse(TypedDict, total=False):
+    """Provider response for fetch_shipment_status."""
+
+    status: str | None
+    tracking_events: list[TrackingEvent]

sendparcel/validators.py

@@ -0,0 +1,20 @@
+"""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
+
+
+def run_validators(
+    data: dict, validators: list[Callable] | None = None
+) -> dict:
+    """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