bidkit 0.1.0__py3-none-any.whl

bidkit/client.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from .auth import EbayAuth, OAuthTokens, TokenCache
+from .config import DEFAULT_TIMEOUT, EbayConfig
+from .errors import EbayConfigError
+from .transport import AsyncEbayTransport, EbayTransport
+
+
+def _authorization_url(
+    config: EbayConfig,
+    *,
+    state: str | None,
+    prompt: str | None,
+    scopes: tuple[str, ...] | None,
+) -> str:
+    if not config.app_id or not config.ru_name:
+        raise EbayConfigError("app_id and ru_name are required to build an authorization URL")
+    return EbayAuth.authorization_url(
+        app_id=config.app_id,
+        ru_name=config.ru_name,
+        scopes=scopes or config.scopes,
+        sandbox=config.sandbox,
+        state=state,
+        prompt=prompt,
+    )
+
+
+def _overridden_config(config: EbayConfig, overrides: Mapping[str, Any]) -> EbayConfig:
+    """Re-validate the explicitly-set fields plus ``overrides`` into a new config."""
+    data = {name: getattr(config, name) for name in config.model_fields_set}
+    return EbayConfig(**{**data, **overrides})
+
+
+if TYPE_CHECKING:
+    from .generated.resources import (
+        AsyncBuyNamespace,
+        AsyncCommerceNamespace,
+        AsyncDeveloperNamespace,
+        AsyncPostOrderNamespace,
+        AsyncSellNamespace,
+        BuyNamespace,
+        CommerceNamespace,
+        DeveloperNamespace,
+        PostOrderNamespace,
+        SellNamespace,
+    )
+
+
+class EbayClient:
+    buy: BuyNamespace
+    commerce: CommerceNamespace
+    developer: DeveloperNamespace
+    post_order: PostOrderNamespace
+    sell: SellNamespace
+
+    def __init__(
+        self,
+        config: EbayConfig | Mapping[str, Any] | None = None,
+        *,
+        http_client: httpx.Client | None = None,
+        token_cache: TokenCache | None = None,
+    ) -> None:
+        self.config = (
+            config if isinstance(config, EbayConfig) else EbayConfig.model_validate(config or {})
+        )
+        self._owns_http = http_client is None
+        self.http = http_client or httpx.Client(timeout=self.config.timeout or DEFAULT_TIMEOUT)
+        self.auth = EbayAuth(self.config, token_cache)
+        self._transport = EbayTransport(self.config, self.auth, self.http)
+
+        from .generated.resources import install_sync_namespaces
+
+        install_sync_namespaces(self)
+
+    @classmethod
+    def from_env(cls) -> EbayClient:
+        return cls(EbayConfig.from_env())
+
+    def with_options(self, **overrides: Any) -> EbayClient:
+        """A scoped client with config fields overridden, e.g.::
+
+            client.with_options(timeout=5.0, max_retries=0).sell.inventory.get_offers(...)
+
+        The returned client shares this client's HTTP connection pool and token cache
+        (no new connections, no re-auth); closing it is a no-op, and any
+        :class:`EbayConfig` field (``timeout``, ``max_retries``, ``marketplace_id``,
+        ``retry_backoff``, ...) can be overridden.
+        """
+        return type(self)(
+            _overridden_config(self.config, overrides),
+            http_client=self.http,
+            token_cache=self.auth.cache,
+        )
+
+    def authorization_url(
+        self,
+        *,
+        state: str | None = None,
+        prompt: str | None = None,
+        scopes: tuple[str, ...] | None = None,
+    ) -> str:
+        """Build the eBay consent URL to send a user to (authorization-code flow)."""
+        return _authorization_url(self.config, state=state, prompt=prompt, scopes=scopes)
+
+    def exchange_code(self, code: str, *, ru_name: str | None = None) -> OAuthTokens:
+        """Exchange a consent ``code`` for tokens and authenticate this client with them.
+
+        Note: this mutates ``self.config`` — the returned ``refresh_token`` is stored on
+        the config so subsequent calls run as the newly authorized user.
+        """
+        tokens = self.auth.exchange_code(self.http, code, ru_name=ru_name)
+        self.auth.seed_tokens(tokens)
+        return tokens
+
+    def close(self) -> None:
+        # Only close the transport the SDK created; never an injected, caller-owned client.
+        if self._owns_http:
+            self.http.close()
+
+    def __enter__(self) -> EbayClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def _request(self, **kwargs: Any) -> Any:
+        return self._transport.request(**kwargs)
+
+    def _stream(self, **kwargs: Any) -> AbstractContextManager[httpx.Response]:
+        return self._transport.stream(**kwargs)
+
+
+class AsyncEbayClient:
+    buy: AsyncBuyNamespace
+    commerce: AsyncCommerceNamespace
+    developer: AsyncDeveloperNamespace
+    post_order: AsyncPostOrderNamespace
+    sell: AsyncSellNamespace
+
+    def __init__(
+        self,
+        config: EbayConfig | Mapping[str, Any] | None = None,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        token_cache: TokenCache | None = None,
+    ) -> None:
+        self.config = (
+            config if isinstance(config, EbayConfig) else EbayConfig.model_validate(config or {})
+        )
+        self._owns_http = http_client is None
+        self.http = http_client or httpx.AsyncClient(timeout=self.config.timeout or DEFAULT_TIMEOUT)
+        self.auth = EbayAuth(self.config, token_cache)
+        self._transport = AsyncEbayTransport(self.config, self.auth, self.http)
+
+        from .generated.resources import install_async_namespaces
+
+        install_async_namespaces(self)
+
+    @classmethod
+    def from_env(cls) -> AsyncEbayClient:
+        return cls(EbayConfig.from_env())
+
+    def with_options(self, **overrides: Any) -> AsyncEbayClient:
+        """A scoped client with config fields overridden — see :meth:`EbayClient.with_options`."""
+        return type(self)(
+            _overridden_config(self.config, overrides),
+            http_client=self.http,
+            token_cache=self.auth.cache,
+        )
+
+    def authorization_url(
+        self,
+        *,
+        state: str | None = None,
+        prompt: str | None = None,
+        scopes: tuple[str, ...] | None = None,
+    ) -> str:
+        """Build the eBay consent URL to send a user to (authorization-code flow)."""
+        return _authorization_url(self.config, state=state, prompt=prompt, scopes=scopes)
+
+    async def exchange_code(self, code: str, *, ru_name: str | None = None) -> OAuthTokens:
+        """Exchange a consent ``code`` for tokens and authenticate this client with them.
+
+        Note: this mutates ``self.config`` — the returned ``refresh_token`` is stored on
+        the config so subsequent calls run as the newly authorized user.
+        """
+        tokens = await self.auth.async_exchange_code(self.http, code, ru_name=ru_name)
+        self.auth.seed_tokens(tokens)
+        return tokens
+
+    async def close(self) -> None:
+        # Only close the transport the SDK created; never an injected, caller-owned client.
+        if self._owns_http:
+            await self.http.aclose()
+
+    async def __aenter__(self) -> AsyncEbayClient:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+    async def _request(self, **kwargs: Any) -> Any:
+        return await self._transport.request(**kwargs)
+
+    def _stream(self, **kwargs: Any) -> AbstractAsyncContextManager[httpx.Response]:
+        return self._transport.stream(**kwargs)

bidkit/config.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError
+
+SecretValue = SecretStr | str
+
+logger = logging.getLogger("bidkit.config")
+
+# Timeout for HTTP clients the SDK creates itself when EbayConfig.timeout is unset.
+DEFAULT_TIMEOUT = 30.0
+
+
+class EbaySigningConfig(BaseModel):
+    """Credentials for eBay digital-signature (message signing).
+
+    Required by the Finances API and several payout/refund operations. ``jwe`` is the
+    encrypted public key returned by the Key Management API; ``private_key`` is the
+    matching PEM (or bare base64 PKCS#8) private key; ``digest`` selects the
+    content-digest algorithm.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    jwe: str
+    private_key: SecretValue
+    digest: Literal["sha256", "sha512"] = "sha256"
+    # Escape hatch: sign every request instead of only the operations eBay
+    # requires signatures for, in case eBay expands the signed-API list before
+    # the SDK catches up.
+    sign_all: bool = False
+
+    @property
+    def private_key_value(self) -> str:
+        value = _secret_value(self.private_key)
+        if value is None:
+            raise ValueError("signing private_key is empty")
+        return value
+
+    @classmethod
+    def from_key_file(cls, path: str | Path) -> EbaySigningConfig:
+        """Load signing material from an ebay-cli style ``signing-key.json``."""
+        data = json.loads(Path(path).expanduser().read_text())
+        private_key = data.get("privateKeyPem") or data.get("privateKey")
+        if not data.get("jwe") or not private_key:
+            raise ValueError(f"Signing key file {path} is missing 'jwe' and/or a private key")
+        # ebay-cli files sometimes put the KEY algorithm (e.g. "ED25519") in
+        # "cipher"; only sha256/sha512 are content-digest choices, anything else
+        # falls back to the default.
+        raw_digest = str(data.get("cipher") or "").lower()
+        digest: Literal["sha256", "sha512"] = "sha512" if raw_digest == "sha512" else "sha256"
+        return cls(jwe=data["jwe"], private_key=private_key, digest=digest)
+
+
+class EbayConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    app_id: str | None = None
+    cert_id: SecretValue | None = None
+    dev_id: str | None = None
+    ru_name: str | None = None
+    sandbox: bool = False
+
+    marketplace_id: str = "EBAY_US"
+    accept_language: str | None = "en-US"
+    content_language: str | None = "en-US"
+
+    access_token: SecretValue | None = None
+    refresh_token: SecretValue | None = None
+    scopes: tuple[str, ...] = ("https://api.ebay.com/oauth/api_scope",)
+    auto_refresh: bool = True
+
+    signing: EbaySigningConfig | None = None
+
+    # None means "use the HTTP client's own timeout" (30 s for SDK-created clients);
+    # a set value is applied per request and wins over an injected client's default.
+    timeout: float | None = Field(default=None, gt=0)
+    base_url_override: str | None = None
+
+    # Retry policy for transient responses (429 + transient 5xx) and connection errors.
+    max_retries: int = Field(default=2, ge=0)
+    retry_statuses: tuple[int, ...] = (429, 500, 502, 503, 504)
+    retry_backoff: float = Field(default=0.5, ge=0)
+    retry_max_backoff: float = Field(default=60.0, ge=0)
+    respect_retry_after: bool = True
+
+    @classmethod
+    def from_env(cls, prefix: str = "EBAY_") -> EbayConfig:
+        def value(name: str) -> str | None:
+            raw = os.getenv(prefix + name)
+            return raw if raw not in (None, "") else None
+
+        scopes = value("SCOPES")
+        data: dict[str, Any] = {
+            "app_id": value("APP_ID"),
+            "cert_id": value("CERT_ID"),
+            "dev_id": value("DEV_ID"),
+            "ru_name": value("RU_NAME"),
+            "marketplace_id": value("MARKETPLACE_ID") or "EBAY_US",
+            "accept_language": value("ACCEPT_LANGUAGE") or "en-US",
+            "content_language": value("CONTENT_LANGUAGE") or "en-US",
+            "access_token": value("ACCESS_TOKEN"),
+            "refresh_token": value("REFRESH_TOKEN"),
+            "base_url_override": value("BASE_URL"),
+        }
+        sandbox = value("SANDBOX")
+        if sandbox is not None:
+            data["sandbox"] = sandbox.strip().lower() in {"1", "true", "yes", "on"}
+        if scopes:
+            data["scopes"] = tuple(scope for scope in scopes.split() if scope)
+
+        signing_key_file = value("SIGNING_KEY_FILE")
+        signing_jwe = value("SIGNING_JWE")
+        if signing_key_file:
+            data["signing"] = EbaySigningConfig.from_key_file(signing_key_file)
+        else:
+            signing_private_key = value("SIGNING_PRIVATE_KEY")
+            if signing_jwe and signing_private_key:
+                data["signing"] = EbaySigningConfig.model_validate(
+                    {
+                        "jwe": signing_jwe,
+                        "private_key": signing_private_key,
+                        "digest": value("SIGNING_DIGEST") or "sha256",
+                    }
+                )
+
+        return cls(**{key: val for key, val in data.items() if val is not None})
+
+    @classmethod
+    def from_file(
+        cls,
+        path: str | Path = "~/.config/ebay-cli/config.json",
+        *,
+        signing_key_file: str | Path | None = None,
+    ) -> EbayConfig:
+        """Load an ebay-cli style ``config.json``.
+
+        Credentials live under a ``credentials`` object (or at the top level) with the
+        aliases ebay-cli uses: ``app_id``/``client_id``, ``cert_id``/``client_secret``,
+        ``ru_name``/``redirect_uri``, ``granted_scopes``/``scopes``. Top-level
+        ``environment`` ("sandbox"/"production") and ``marketplace_default`` map to
+        ``sandbox`` and ``marketplace_id``. A ``signing-key.json`` next to the config is
+        picked up automatically; pass ``signing_key_file`` to point elsewhere.
+        """
+        config_path = Path(path).expanduser()
+        raw = json.loads(config_path.read_text())
+        creds = raw.get("credentials", raw)
+        if not isinstance(creds, dict):
+            raise ValueError(f"Config file {config_path} has no usable 'credentials' object")
+
+        def alias(*names: str) -> Any:
+            return next((creds[name] for name in names if creds.get(name)), None)
+
+        scopes = alias("granted_scopes", "scopes")
+        data: dict[str, Any] = {
+            "app_id": alias("app_id", "client_id"),
+            "cert_id": alias("cert_id", "client_secret"),
+            "dev_id": alias("dev_id"),
+            "ru_name": alias("ru_name", "redirect_uri"),
+            "refresh_token": alias("refresh_token"),
+            "marketplace_id": raw.get("marketplace_default"),
+        }
+        if raw.get("environment"):
+            data["sandbox"] = raw["environment"] == "sandbox"
+        if scopes:
+            data["scopes"] = tuple(scopes.split()) if isinstance(scopes, str) else tuple(scopes)
+
+        if signing_key_file is not None:
+            # Explicitly requested: let a broken file raise.
+            data["signing"] = EbaySigningConfig.from_key_file(signing_key_file)
+        else:
+            sibling = config_path.with_name("signing-key.json")
+            if sibling.exists():
+                # Auto-detected: best effort, since most flows never need signing
+                # and a stub or foreign-format file must not break config loading.
+                try:
+                    data["signing"] = EbaySigningConfig.from_key_file(sibling)
+                except (ValueError, ValidationError) as exc:
+                    logger.warning("ignoring unusable signing key file %s: %s", sibling, exc)
+
+        return cls(**{key: val for key, val in data.items() if val is not None})
+
+    def api_root(self, subdomain: str = "api") -> str:
+        if self.base_url_override:
+            return self.base_url_override.rstrip("/")
+        sandbox = ".sandbox" if self.sandbox else ""
+        return f"https://{subdomain}{sandbox}.ebay.com"
+
+    @property
+    def oauth_token_url(self) -> str:
+        return f"{self.api_root('api')}/identity/v1/oauth2/token"
+
+    @property
+    def client_secret(self) -> str | None:
+        return _secret_value(self.cert_id)
+
+    @property
+    def bearer_token(self) -> str | None:
+        return _secret_value(self.access_token)
+
+    @property
+    def refresh_token_value(self) -> str | None:
+        return _secret_value(self.refresh_token)
+
+
+def _secret_value(value: SecretValue | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, SecretStr):
+        return value.get_secret_value()
+    return value

bidkit/errors.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import orjson
+
+
+class EbaySDKError(Exception):
+    """Base exception for all SDK-level failures."""
+
+
+class EbayConfigError(EbaySDKError):
+    """Raised when SDK configuration is incomplete or invalid."""
+
+
+class EbayTransportError(EbaySDKError):
+    """Raised for network-level failures before eBay returns a response."""
+
+
+class EbayAuthError(EbaySDKError):
+    """Raised when OAuth token acquisition or refresh fails."""
+
+
+class EbayAPIError(EbaySDKError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response: httpx.Response | None = None,
+        payload: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        self.payload = payload
+        self.request_id = request_id
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> EbayAPIError:
+        payload: Any
+        try:
+            payload = orjson.loads(response.content)
+        except orjson.JSONDecodeError:
+            payload = response.text
+
+        message = response.reason_phrase or f"eBay API returned HTTP {response.status_code}"
+        if isinstance(payload, dict):
+            errors = payload.get("errors")
+            if isinstance(errors, list) and errors:
+                first = errors[0]
+                if isinstance(first, dict):
+                    message = first.get("message") or first.get("longMessage") or message
+            elif payload.get("error_description"):
+                message = str(payload["error_description"])
+            elif payload.get("message"):
+                message = str(payload["message"])
+
+        return cls(
+            message,
+            status_code=response.status_code,
+            response=response,
+            payload=payload,
+            request_id=response.headers.get("x-ebay-c-request-id")
+            or response.headers.get("x-ebay-request-id"),
+        )

bidkit/generated/__init__.py

@@ -0,0 +1 @@
+"""Generated OpenAPI clients and models."""

bidkit/generated/models/__init__.py

@@ -0,0 +1 @@
+"""Generated Pydantic model modules."""