Merge branch 'main' into feature/41-swap-payment-model

Author: ALIPHATICHYD

poetry.lock

@@ -10,6 +10,7 @@ packages = [{include = "shade", from = "src"}]
 python = "^3.10"
 httpx = "^0.28.1"
 stellar-sdk = "^13.2.1"
+pydantic = "^2.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"

pyproject.toml

@@ -14,8 +14,9 @@
     HTTPError,
     RateLimitError,
     ShadeError,
+    SignatureVerificationError,
 )
-from .models import SwapPayment, SwapStatus
+from .models import Merchant, ShadeObject, Transfer, TransferStatus
 
 __version__ = "0.1.0"
 
@@ -29,14 +30,17 @@
     "Gateway",
     "HTTPError",
     "InvalidRequestError",
+    "Merchant",
     "NetworkError",
     "NotFoundError",
     "RateLimitError",
     "ShadeClient",
     "ShadeError",
+    "SignatureVerificationError",
+    "ShadeObject",
     "SyncHTTPClient",
-    "SwapPayment",
-    "SwapStatus",
+    "Transfer",
+    "TransferStatus",
     "config",
     "api_base",
     "environment",

src/shade/__init__.py

@@ -163,6 +163,40 @@ def from_response(
         return cls(message, status_code=404, response_body=response_body)
 
 
+class SignatureVerificationError(ShadeError):
+    """
+    Raised by ``Webhook.construct_event()`` when the HMAC-SHA256 signature in
+    the ``Shade-Signature`` header does not match the signature computed for
+    the payload.
+
+    Attributes:
+        header: The raw ``Shade-Signature`` header value as received.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        header: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.header = header
+
+    @classmethod
+    def from_mismatch(cls, header: Optional[str] = None) -> "SignatureVerificationError":
+        """Construct the error for a computed/received signature mismatch.
+
+        The expected signature is deliberately not accepted as an argument
+        here, so it can never end up in the exception message.
+        """
+        message = (
+            "Webhook signature verification failed: the received signature "
+            "does not match the signature computed for this payload. This "
+            "usually means the webhook secret is incorrect, or the payload "
+            "was modified in transit."
+        )
+        return cls(message, header=header)
+
+
 class NetworkError(ShadeError):
     """Raised when the SDK cannot complete a network request."""
 

src/shade/base.py

@@ -1,10 +1,8 @@
 """
-Shade data models.
+Shade API response models.
 """
+from .base import ShadeObject
+from .merchant import Merchant
+from .transfer import Transfer, TransferStatus
 
-from .swap import SwapPayment, SwapStatus
-
-__all__ = [
-    "SwapPayment",
-    "SwapStatus",
-]
+__all__ = ["Merchant", "ShadeObject", "Transfer", "TransferStatus"]

src/shade/errors.py

@@ -0,0 +1,86 @@
+"""
+Base model shared by every Shade API response object.
+"""
+from __future__ import annotations
+
+from typing import Any, ClassVar, Optional
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ..errors import InvalidRequestError
+
+
+class ShadeObject(BaseModel):
+    """Base class for API response models.
+
+    Subclasses get dict round-tripping (:meth:`from_dict` / :meth:`to_dict`) and a
+    readable ``repr``. Unknown fields returned by the API are preserved rather than
+    rejected, so a server-side addition never breaks an older SDK.
+
+    Attributes:
+        _id_field: Name of the field shown in ``repr``. Subclasses that do not use
+            a plain ``id`` should override it (e.g. ``_id_field = "invoice_id"``).
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    _id_field: ClassVar[str] = "id"
+
+    def __init__(self, **data: Any) -> None:
+        try:
+            super().__init__(**data)
+        except ValidationError as exc:
+            raise _as_invalid_request(type(self), exc) from exc
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ShadeObject":
+        """Build a model from a decoded JSON object.
+
+        Raises:
+            InvalidRequestError: If ``data`` is not a dict or fails validation.
+        """
+        if not isinstance(data, dict):
+            raise InvalidRequestError(
+                f"{cls.__name__}.from_dict() expects a dict, got "
+                f"{type(data).__name__}"
+            )
+        return cls(**data)
+
+    def to_dict(self, **kwargs: Any) -> dict:
+        """Return the model as a plain dict, keyed by field alias where one exists.
+
+        Any keyword arguments are forwarded to ``model_dump``.
+        """
+        kwargs.setdefault("by_alias", True)
+        return self.model_dump(**kwargs)
+
+    def __repr__(self) -> str:
+        identifier = self._identifier()
+        if identifier is None:
+            return f"<{type(self).__name__}>"
+        return f"<{type(self).__name__} {self._id_field}={identifier!r}>"
+
+    def _identifier(self) -> Optional[Any]:
+        """Value of the model's primary ID field, or ``None`` when it has none."""
+        return getattr(self, self._id_field, None)
+
+
+def _as_invalid_request(
+    model: type[BaseModel],
+    exc: ValidationError,
+) -> InvalidRequestError:
+    """Translate a pydantic ValidationError into the SDK's InvalidRequestError."""
+    errors = exc.errors()
+    field_errors: dict[str, list[str]] = {}
+    for error in errors:
+        location = ".".join(str(part) for part in error["loc"]) or "__root__"
+        field_errors.setdefault(location, []).append(error["msg"])
+
+    count = len(errors)
+    plural = "" if count == 1 else "s"
+    first = next(iter(field_errors), None)
+    return InvalidRequestError(
+        f"{count} validation error{plural} for {model.__name__}",
+        param=first,
+        field_errors=field_errors,
+    )

src/shade/merchant.py

@@ -0,0 +1,81 @@
+"""
+Merchant model.
+
+Mirrors the Shade backend's Prisma ``Merchant`` schema, with field names
+converted from ``camelCase`` (Prisma/JSON) to ``snake_case`` (Python) via
+pydantic field aliases.  The :attr:`Merchant.merchant_id` field (from Prisma
+``merchantId: Int``) is the numeric identifier the Soroban contract stamps onto
+every invoice, making it the bridge between the backend and the on-chain world.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import Field, StrictBool, field_validator
+from stellar_sdk.strkey import StrKey
+
+from .base import ShadeObject
+
+
+class Merchant(ShadeObject):
+    """A Shade merchant account.
+
+    Build one from an API response with :meth:`ShadeObject.from_dict`, which maps
+    camelCase JSON keys to the snake_case fields below.  ``address`` must be a
+    valid Stellar ed25519 public key and ``active`` / ``verified`` must be real
+    booleans; anything else raises
+    :class:`~shade.errors.InvalidRequestError` on construction.
+    """
+
+    id: str
+    merchant_id: int = Field(alias="merchantId")
+    address: str
+    active: StrictBool
+    verified: StrictBool
+    account: Optional[str] = None
+    email: Optional[str] = None
+    first_name: Optional[str] = Field(default=None, alias="firstName")
+    last_name: Optional[str] = Field(default=None, alias="lastName")
+    business_name: Optional[str] = Field(default=None, alias="businessName")
+    category: Optional[str] = None
+    description: Optional[str] = None
+    logo: Optional[str] = None
+    webhook: Optional[str] = None
+
+    @field_validator("merchant_id", mode="before")
+    @classmethod
+    def _reject_bool_merchant_id(cls, value: object) -> object:
+        # pydantic would otherwise coerce ``True``/``False`` to 1/0; a boolean is
+        # never a valid merchant id, so reject it rather than silently accept it.
+        if isinstance(value, bool):
+            raise ValueError("merchant_id must be an integer, not a boolean")
+        return value
+
+    @field_validator("address")
+    @classmethod
+    def _validate_address(cls, value: str) -> str:
+        if not StrKey.is_valid_ed25519_public_key(value):
+            raise ValueError(
+                "address must be a valid Stellar public key "
+                "(starts with 'G', 56 characters)"
+            )
+        return value
+
+    @property
+    def display_name(self) -> Optional[str]:
+        """The most informative human-readable name available.
+
+        Prefers ``business_name``; falls back to the person's full name
+        (``"{first_name} {last_name}"``); finally ``email``.  Each candidate is
+        trimmed, so a blank or whitespace-only value falls through to the next
+        one rather than being returned.  ``None`` when nothing is available.
+        """
+        business_name = (self.business_name or "").strip()
+        if business_name:
+            return business_name
+        first_name = (self.first_name or "").strip()
+        last_name = (self.last_name or "").strip()
+        full_name = " ".join(part for part in (first_name, last_name) if part)
+        if full_name:
+            return full_name
+        return (self.email or "").strip() or None

src/shade/models/__init__.py

@@ -0,0 +1,82 @@
+"""
+Transfer model.
+
+Represents a payout of funds from the merchant wallet to a destination
+address on the Stellar network. Field names are converted from ``camelCase``
+(backend/JSON) to ``snake_case`` (Python) via pydantic field aliases, matching
+the convention established by :class:`~shade.models.merchant.Merchant`.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Optional
+
+from pydantic import Field, field_validator
+from stellar_sdk.strkey import StrKey
+
+from .base import ShadeObject
+
+
+class TransferStatus(str, Enum):
+    """Lifecycle status of a transfer."""
+
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class Transfer(ShadeObject):
+    """A payout of funds from the merchant wallet to a destination address.
+
+    Build one from an API response with :meth:`ShadeObject.from_dict`, which
+    maps camelCase JSON keys to the snake_case fields below. ``asset`` falls
+    back to ``"XLM"`` when the API omits it (or sends it as ``null``), and
+    ``status`` is always coerced to a :class:`TransferStatus` member.
+    """
+
+    id: str
+    source_address: str = Field(alias="sourceAddress")
+    destination_address: str = Field(alias="destinationAddress")
+    amount: Decimal
+    asset: str = "XLM"
+    status: TransferStatus
+    stellar_tx_hash: Optional[str] = Field(default=None, alias="stellarTxHash")
+    fee: Optional[Decimal] = None
+    created_at: datetime = Field(alias="createdAt")
+
+    @field_validator("asset", mode="before")
+    @classmethod
+    def _default_asset(cls, value: object) -> object:
+        # Covers both a missing key (pydantic would already default it) and an
+        # API response that sends the key as an explicit null/empty string.
+        # Other falsy-but-wrong types (e.g. False, 0) are left alone so
+        # pydantic's normal type validation rejects them.
+        if value is None or value == "":
+            return "XLM"
+        return value
+
+    @field_validator("source_address", "destination_address")
+    @classmethod
+    def _validate_stellar_address(cls, value: str) -> str:
+        if not StrKey.is_valid_ed25519_public_key(value):
+            raise ValueError(
+                "must be a valid Stellar public key (starts with 'G', 56 characters)"
+            )
+        return value
+
+    @field_validator("amount")
+    @classmethod
+    def _amount_must_be_positive(cls, value: Decimal) -> Decimal:
+        if value <= 0:
+            raise ValueError("amount must be greater than 0")
+        return value
+
+    @field_validator("fee")
+    @classmethod
+    def _fee_must_not_be_negative(cls, value: Optional[Decimal]) -> Optional[Decimal]:
+        if value is not None and value < 0:
+            raise ValueError("fee must not be negative")
+        return value