refactor: move Merchant into models/ on the pydantic ShadeObject base

Rebuild the Merchant model on the shared pydantic ShadeObject introduced on
main (#47), replacing the standalone plain-Python model and base.

- Move src/shade/merchant.py -> src/shade/models/merchant.py and delete the
  now-redundant src/shade/base.py.
- Map camelCase JSON to snake_case fields with pydantic Field(alias=...);
  from_dict / to_dict / repr come from ShadeObject.
- Enforce validation via pydantic: StrictBool for active/verified (no
  silent coercion of strings like "false"), a Stellar public-key
  field_validator on address, and a before-validator rejecting boolean
  merchant_id (which pydantic would otherwise coerce to 1/0). All surface as
  InvalidRequestError through the base.
- Export Merchant from shade.models and the top-level package.
- Update tests: unknown keys are now preserved (extra="allow"), the
  merchant_id error param is the "merchantId" alias, and add a boolean
  merchant_id rejection case.

Author: giftexceed

src/shade/__init__.py

@@ -2,12 +2,10 @@
 from types import ModuleType
 from typing import Optional
 
-from .base import ShadeObject
 from .client import ShadeClient
 from .config import config, Environment
 from .gateway import Gateway
 from .http import AsyncHTTPClient, SyncHTTPClient
-from .merchant import Merchant
 from .errors import (
     AuthenticationError,
     InvalidRequestError,
@@ -17,7 +15,7 @@
     RateLimitError,
     ShadeError,
 )
-from .models import ShadeObject
+from .models import Merchant, ShadeObject
 
 __version__ = "0.1.0"
 

src/shade/base.py

@@ -2,5 +2,6 @@
 Shade API response models.
 """
 from .base import ShadeObject
+from .merchant import Merchant
 
-__all__ = ["ShadeObject"]
+__all__ = ["Merchant", "ShadeObject"]

src/shade/merchant.py

@@ -0,0 +1,79 @@
+"""
+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
+        full_name = f"{self.first_name or ''} {self.last_name or ''}".strip()
+        if full_name:
+            return full_name
+        return (self.email or "").strip() or None

src/shade/models/__init__.py

@@ -53,9 +53,12 @@ def test_merchant_is_exported_from_package():
     assert issubclass(Merchant, ShadeObject)
 
 
-def test_from_dict_ignores_unknown_keys():
-    merchant = Merchant.from_dict(_api_response(createdAt="2026-01-01", extra="x"))
+def test_from_dict_preserves_unknown_keys():
+    # The ShadeObject base allows extra fields so a server-side addition never
+    # breaks an older SDK; the known fields still map correctly.
+    merchant = Merchant.from_dict(_api_response(createdAt="2026-01-01"))
     assert merchant.merchant_id == 42
+    assert merchant.to_dict()["createdAt"] == "2026-01-01"
 
 
 def test_from_dict_requires_a_mapping():
@@ -83,7 +86,14 @@ def test_address_wrong_length_is_rejected():
 def test_non_integer_merchant_id_raises():
     with pytest.raises(InvalidRequestError) as exc_info:
         Merchant.from_dict(_api_response(merchantId="abc"))
-    assert exc_info.value.param == "merchant_id"
+    assert exc_info.value.param == "merchantId"
+
+
+def test_boolean_merchant_id_is_rejected():
+    # A bool would otherwise be coerced to 1/0; it is never a valid merchant id.
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Merchant.from_dict(_api_response(merchantId=True))
+    assert exc_info.value.param == "merchantId"
 
 
 @pytest.mark.parametrize("field", ["active", "verified"])