feat(client): implement ShadeClient for per-instance configuration

Implements issue #2. ShadeClient binds credentials and connection settings
to a single object so a multi-tenant application can hold one client per
merchant instead of mutating the global shade module config.

- ShadeClient takes api_key, environment, api_base, timeout and max_retries,
  each falling back to the matching global setting when omitted. The fallback
  resolves once at construction, so later global changes never mutate an
  existing client.
- Adds a global shade.api_key setting backing that fallback.
- ShadeClient.from_env() builds a client from SHADE_API_KEY and
  SHADE_ENVIRONMENT, with keyword arguments overriding either.
- A missing api_key with no global key set now raises AuthenticationError
  instead of ValueError, naming all three ways to supply one.
- BaseResource gives resources the optional client= kwarg, resolving to the
  shared global client when omitted. The client is resolved per access, so a
  resource built before shade.api_key was assigned still picks it up.

ShadeClient was previously an alias for Gateway, with a separate unrelated
ShadeClient in client.py. Gateway is now a ShadeClient subclass carrying the
payment methods, and the httpx-backed transport that occupied client.py moves
to http.py as HTTPXTransport, alongside the other transports. The two tests
asserting the old alias now assert the subclass relationship.

Also fixes http.py resolving `from . import config` to the config module
rather than the Config instance. That only worked because of the order of
imports in __init__.py, and broke as soon as client.py imported http.py
earlier in the chain.

Author: daveades

src/shade/__init__.py

@@ -2,10 +2,11 @@
 from types import ModuleType
 from typing import Optional
 
-from .client import ShadeClient
+from .client import ShadeClient, default_client, reset_default_client
 from .config import config, Environment
 from .gateway import Gateway
 from .http import AsyncHTTPClient, SyncHTTPClient
+from .resources import BaseResource
 from .errors import (
     AuthenticationError,
     InvalidRequestError,
@@ -20,14 +21,12 @@
 
 __version__ = "0.1.0"
 
-# ShadeClient is an alias for Gateway.
-ShadeClient = Gateway
-
 __all__ = [
     "AssetBalance",
     "AsyncHTTPClient",
     "AuthenticationError",
     "Balance",
+    "BaseResource",
     "Environment",
     "Gateway",
     "HTTPError",
@@ -45,14 +44,27 @@
     "TransferStatus",
     "config",
     "api_base",
+    "api_key",
+    "default_client",
     "environment",
     "max_retries",
+    "reset_default_client",
     "timeout",
 ]
 
 class _ShadeModule(ModuleType):
     """Module subclass that exposes config-backed attributes on the shade package."""
 
+    @property
+    def api_key(self) -> Optional[str]:
+        from . import config as _config
+        return _config.api_key
+
+    @api_key.setter
+    def api_key(self, value: Optional[str]) -> None:
+        from . import config as _config
+        _config.api_key = value
+
     @property
     def api_base(self) -> Optional[str]:
         from . import config as _config

src/shade/client.py

@@ -1,68 +1,231 @@
-from typing import Any, Mapping, Optional
+"""
+Per-instance SDK configuration.
+
+``ShadeClient`` binds a set of credentials and connection settings to a single
+object, so an application acting on behalf of several merchants can hold one
+client per tenant instead of mutating the global ``shade`` module config.
+Anything left unset falls back to the global config at construction time.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
 
 import httpx
 
-from shade._debug import log_request, log_response
-from shade.config import config
+from .config import Environment, validate_client_settings
+from .config import config as _config
+from .errors import AuthenticationError
+from .http import AsyncHTTPClient, HTTPXTransport, SyncHTTPClient
+
+API_KEY_ENV_VAR = "SHADE_API_KEY"
+ENVIRONMENT_ENV_VAR = "SHADE_ENVIRONMENT"
 
 
 class ShadeClient:
-    """HTTP client for the Shade Payment Gateway API."""
+    """An isolated Shade API client carrying its own credentials and settings.
+
+    Two clients built with different API keys never share state, so a
+    multi-tenant application can keep one per merchant::
+
+        acme = ShadeClient(api_key="sk_live_acme")
+        globex = ShadeClient(api_key="sk_live_globex")
+
+    Every parameter falls back to the matching global setting
+    (``shade.api_key``, ``shade.environment``, …) when omitted, and the fallback
+    is resolved once at construction — later changes to the global config do not
+    retroactively alter an existing client.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Your Shade API key. Defaults to the module-level ``shade.api_key``.
+    environment : str | Environment, optional
+        Controls the Stellar network passphrase and the default API URL.
+        Defaults to the module-level ``shade.environment``.
+    api_base : str, optional
+        Override the API host for this client (local dev, staging, or a
+        self-hosted backend). Takes precedence over the module-level
+        ``shade.api_base`` and the URL derived from ``environment``. Trailing
+        slashes are trimmed.
+    timeout : float, optional
+        Per-request socket timeout in seconds. Defaults to ``shade.timeout``.
+    max_retries : int, optional
+        Automatic retries on HTTP 429 and transient failures. Defaults to
+        ``shade.max_retries``. Set to ``0`` to disable auto-retry.
+    base_url : str
+        Deprecated. Prefer ``api_base``.
+    debug : bool
+        Log requests and responses for this client. The global
+        ``shade.config.debug`` enables logging regardless of this flag.
+    http_client : httpx.Client, optional
+        Reuse an existing httpx client instead of creating one. The caller
+        keeps ownership: :meth:`close` will not close a client it was given.
+
+    Raises
+    ------
+    AuthenticationError
+        If no API key is given and no global ``shade.api_key`` is set.
+    ValueError
+        If ``timeout`` or ``max_retries`` is out of range, or ``environment``
+        is not a recognised value.
+    """
 
     def __init__(
         self,
-        api_key: str,
-        base_url: str = "https://api.shadeprotocol.io",
+        api_key: Optional[str] = None,
+        environment: Optional[Environment | str] = None,
+        api_base: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        base_url: str = "",
         debug: bool = False,
         http_client: Optional[httpx.Client] = None,
-    ):
-        self.api_key = api_key
-        self.base_url = base_url.rstrip("/")
+    ) -> None:
+        resolved_api_key = api_key or _config.api_key
+        if not resolved_api_key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= to ShadeClient, set "
+                f"shade.api_key, or set the {API_KEY_ENV_VAR} environment variable."
+            )
+        self.api_key = resolved_api_key
+
+        if environment is not None:
+            self.environment = _config.parse_environment(environment)
+        else:
+            self.environment = _config.environment
+
+        self.max_retries = _config.max_retries if max_retries is None else max_retries
+        self.timeout = _config.timeout if timeout is None else timeout
+        validate_client_settings(self.timeout, self.max_retries)
+
+        # Resolution order: explicit api_base > module-level shade.api_base
+        # > legacy base_url > environment URL
+        resolved = api_base or _config.api_base or base_url or self.environment.base_url
+        self._base_url = resolved.rstrip("/")
         self.debug = debug
-        self._http = http_client or httpx.Client()
-        self._owns_http_client = http_client is None
+
+        self._http = SyncHTTPClient(
+            base_url=self._base_url,
+            api_key=self.api_key,
+            max_retries=self.max_retries,
+            timeout=self.timeout,
+        )
+        self._async_http = AsyncHTTPClient(
+            base_url=self._base_url,
+            api_key=self.api_key,
+            max_retries=self.max_retries,
+            timeout=self.timeout,
+        )
+        self._client = HTTPXTransport(
+            api_key=self.api_key,
+            base_url=self._base_url,
+            debug=debug,
+            http_client=http_client,
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "ShadeClient":
+        """Build a client from ``SHADE_API_KEY`` and ``SHADE_ENVIRONMENT``.
+
+        Either variable may be absent, in which case the usual global-config
+        fallback applies — so a missing ``SHADE_API_KEY`` with no
+        ``shade.api_key`` set raises :class:`~shade.errors.AuthenticationError`.
+
+        Any keyword argument overrides the corresponding environment variable,
+        letting callers take the key from the environment while setting the rest
+        explicitly::
+
+            client = ShadeClient.from_env(timeout=5.0)
+        """
+        env_kwargs: Dict[str, Any] = {}
+        api_key = os.environ.get(API_KEY_ENV_VAR)
+        if api_key:
+            env_kwargs["api_key"] = api_key
+        environment = os.environ.get(ENVIRONMENT_ENV_VAR)
+        if environment:
+            env_kwargs["environment"] = environment
+        env_kwargs.update(overrides)
+        return cls(**env_kwargs)
+
+    @property
+    def api_base(self) -> str:
+        """The resolved API base URL this client sends requests to."""
+        return self._base_url
 
     def close(self) -> None:
-        if self._owns_http_client:
-            self._http.close()
+        self._client.close()
 
     def __enter__(self) -> "ShadeClient":
         return self
 
     def __exit__(self, *args: Any) -> None:
         self.close()
 
-    def _should_debug(self) -> bool:
-        return self.debug or config.debug
-
-    def _default_headers(self) -> dict[str, str]:
-        return {"Authorization": f"Bearer {self.api_key}"}
-
     def request(
         self,
         method: str,
         path: str,
         *,
-        headers: Optional[Mapping[str, str]] = None,
+        headers: Optional[Dict[str, str]] = None,
         json: Any = None,
         content: Optional[bytes] = None,
     ) -> httpx.Response:
-        normalized_path = path if path.startswith("/") else f"/{path}"
-        url = f"{self.base_url}{normalized_path}"
-        request_headers = {**self._default_headers(), **(headers or {})}
-
-        if self._should_debug():
-            log_request(method, url, request_headers, content if content is not None else json)
-
-        response = self._http.request(
+        """Send a request and return the raw ``httpx.Response``."""
+        return self._client.request(
             method,
-            url,
-            headers=request_headers,
+            path,
+            headers=headers,
             json=json,
             content=content,
         )
 
-        if self._should_debug():
-            log_response(response.status_code, response.headers, response.text)
+    def __repr__(self) -> str:
+        return (
+            f"<{type(self).__name__} api_key={_mask_api_key(self.api_key)!r} "
+            f"environment={self.environment.value!r} api_base={self._base_url!r}>"
+        )
+
+
+def _mask_api_key(api_key: str) -> str:
+    """Show only the last four characters of a key, for use in reprs."""
+    if len(api_key) <= 4:
+        return "****"
+    return "*" * (len(api_key) - 4) + api_key[-4:]
+
+
+_default_client: Optional[ShadeClient] = None
+_default_client_settings: Optional[tuple] = None
+
+
+def default_client() -> ShadeClient:
+    """Return the shared client built from the global ``shade`` config.
+
+    Resources fall back to this when constructed without an explicit
+    ``client=``. The instance is cached, but rebuilt whenever a global setting
+    changes, so assigning ``shade.api_key`` after the first call still takes
+    effect.
+
+    Raises:
+        AuthenticationError: If no global ``shade.api_key`` has been set.
+    """
+    global _default_client, _default_client_settings
+
+    settings = (
+        _config.api_key,
+        _config.environment,
+        _config.api_base,
+        _config.timeout,
+        _config.max_retries,
+    )
+    if _default_client is None or _default_client_settings != settings:
+        _default_client = ShadeClient()
+        _default_client_settings = settings
+    return _default_client
+
 
-        return response
+def reset_default_client() -> None:
+    """Drop the cached global client. Primarily useful in tests."""
+    global _default_client, _default_client_settings
+    _default_client = None
+    _default_client_settings = None

src/shade/config.py

@@ -10,6 +10,7 @@ class Config:
 
     def __init__(self):
         self.debug: bool = False
+        self.api_key: Optional[str] = None
         self._api_base: Optional[str] = None
         self.timeout: float = DEFAULT_TIMEOUT
         self.max_retries: int = DEFAULT_MAX_RETRIES