woltapi 0.0.1__py3-none-any.whl

woltapi/credentials.py

@@ -0,0 +1,67 @@
+"""Credential handling with explicit ordering-host scopes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from .services import ServiceHost
+
+
+class SessionCredentials:
+    """Caller-provided request headers, scoped to one ordering host each.
+
+    No header name or value is inferred from the captured browser traffic. A
+    caller must provide credentials obtained through its own approved session
+    integration, and remains responsible for their validity and lifecycle.
+    """
+
+    __slots__ = ("_headers",)
+
+    def __init__(
+        self,
+        *,
+        restaurant_headers: Mapping[str, str] | None = None,
+        consumer_headers: Mapping[str, str] | None = None,
+        payment_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self._headers = MappingProxyType(
+            {
+                ServiceHost.RESTAURANT: _freeze_headers(restaurant_headers),
+                ServiceHost.CONSUMER: _freeze_headers(consumer_headers),
+                ServiceHost.PAYMENT: _freeze_headers(payment_headers),
+            }
+        )
+
+    def headers_for(self, service: ServiceHost) -> Mapping[str, str]:
+        """Return the immutable headers configured for one known service."""
+
+        return self._headers[service]
+
+    def __repr__(self) -> str:
+        configured = ", ".join(
+            service.value for service, headers in self._headers.items() if headers
+        )
+        return f"SessionCredentials(configured_services=({configured}))"
+
+
+def _freeze_headers(headers: Mapping[str, str] | None) -> Mapping[str, str]:
+    if headers is None:
+        return MappingProxyType({})
+    if not isinstance(headers, Mapping):
+        raise TypeError("Session credential headers must be a mapping.")
+
+    frozen: dict[str, str] = {}
+    for name, value in headers.items():
+        if (
+            not isinstance(name, str)
+            or not name.strip()
+            or "\r" in name
+            or "\n" in name
+            or not isinstance(value, str)
+            or "\r" in value
+            or "\n" in value
+        ):
+            raise ValueError("Session credential headers must contain valid strings.")
+        frozen[name] = value
+    return MappingProxyType(frozen)

woltapi/errors.py

@@ -0,0 +1,101 @@
+"""Privacy-safe exceptions raised by the Wolt client."""
+
+from __future__ import annotations
+
+
+class WoltApiError(Exception):
+    """Base exception for this package."""
+
+
+class SelectionError(WoltApiError):
+    """Caller-provided selection data cannot be safely serialized."""
+
+
+class UnsupportedSelectionError(SelectionError):
+    """A catalog or selection feature is outside the supported checkout scope."""
+
+
+class PurchasePreparationError(WoltApiError):
+    """A selection, quote, consent state, or purchase input is unsafe to submit."""
+
+
+class PurchaseAuthorizationError(WoltApiError):
+    """Caller authorization is absent or bound to a different prepared order."""
+
+
+class PurchaseAttemptStoreError(WoltApiError):
+    """Durable local purchase-attempt state could not be safely updated."""
+
+
+class DuplicatePurchaseAttempt(WoltApiError):
+    """The same authorized attempt was already recorded locally."""
+
+    def __init__(
+        self, attempt_id: str, state: str, purchase_id: str | None = None
+    ) -> None:
+        self.attempt_id = attempt_id
+        self.state = state
+        self.purchase_id = purchase_id
+        super().__init__(
+            "This authorized purchase attempt was already recorded locally."
+        )
+
+
+class OrderOutcomeUnknown(WoltApiError):
+    """A purchase may have reached the server but no usable success was established."""
+
+    def __init__(self, attempt_id: str, purchase_id: str | None = None) -> None:
+        self.attempt_id = attempt_id
+        self.purchase_id = purchase_id
+        super().__init__("Purchase outcome is unknown; no automatic retry was sent.")
+
+
+class WoltTransportError(WoltApiError):
+    """A request could not safely produce a usable response."""
+
+
+class HTTPStatusError(WoltTransportError):
+    """A service returned a non-success HTTP status."""
+
+    def __init__(self, service: str, status_code: int) -> None:
+        self.service = service
+        self.status_code = status_code
+        super().__init__(
+            f"Wolt {service} request failed with HTTP status {status_code}."
+        )
+
+
+class RequestTimeoutError(WoltTransportError):
+    """A request timed out before a usable response arrived."""
+
+    def __init__(self, service: str) -> None:
+        self.service = service
+        super().__init__(f"Wolt {service} request timed out.")
+
+
+class RequestFailedError(WoltTransportError):
+    """A request failed before a usable response arrived."""
+
+    def __init__(self, service: str) -> None:
+        self.service = service
+        super().__init__(f"Wolt {service} request failed before a response arrived.")
+
+
+class ResponseError(WoltApiError):
+    """A service response could not be safely interpreted."""
+
+
+class ResponseDecodeError(ResponseError):
+    """A response was not valid JSON."""
+
+    def __init__(self, service: str) -> None:
+        self.service = service
+        super().__init__(f"Wolt {service} response was not valid JSON.")
+
+
+class ResponseShapeError(ResponseError):
+    """A response was missing the expected object or collection shape."""
+
+    def __init__(self, service: str) -> None:
+        self.service = service
+        super().__init__(f"Wolt {service} response had an unexpected shape.")

woltapi/models.py

@@ -0,0 +1,47 @@
+"""Small public summaries for discovery operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Venue:
+    """A venue found in a server-driven search result."""
+
+    id: str
+    slug: str
+    title: str | None
+    currency: str | None
+    delivers: bool | None
+    online: bool | None
+
+
+@dataclass(frozen=True)
+class DeliveryTarget:
+    """An opaque saved delivery reference without address details."""
+
+    id: str
+
+
+@dataclass(frozen=True)
+class PaymentMethod:
+    """An enabled saved-card reference without card metadata."""
+
+    id: str
+    type: str
+    is_selected: bool
+    is_default: bool
+
+
+@dataclass(frozen=True)
+class OrderStatus:
+    """A minimal operational order state with an unbounded status string."""
+
+    purchase_id: str
+    status: str
+    currency: str | None
+    payment_amount: int | float | None
+    total_price: int | float | None
+    delivery_price: int | float | None
+    delivery_method: str | None