feat: ebay listing price v1

Author: Leoglme

api/app_types/ebay_browse.py

@@ -0,0 +1,123 @@
+"""eBay Browse API response + aggregated market search shapes."""
+
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class EbayMoney(TypedDict, total=False):
+    """Money block as returned by eBay (``value`` is a numeric string)."""
+
+    value: str
+    currency: str
+
+
+class EbayImage(TypedDict, total=False):
+    imageUrl: str
+
+
+class EbaySeller(TypedDict, total=False):
+    username: str
+    feedbackPercentage: str
+    feedbackScore: int
+
+
+class EbayItemLocation(TypedDict, total=False):
+    country: str
+    postalCode: str
+    stateOrProvince: str
+
+
+class EbayCategoryInfo(TypedDict, total=False):
+    categoryId: str
+    categoryName: str
+
+
+class EbayItemSummary(TypedDict, total=False):
+    """One item summary block from ``/buy/browse/v1/item_summary/search``."""
+
+    itemId: str
+    title: str
+    price: EbayMoney
+    condition: str
+    conditionId: str
+    itemWebUrl: str
+    itemLocation: EbayItemLocation
+    seller: EbaySeller
+    image: EbayImage
+    thumbnailImages: list[EbayImage]
+    additionalImages: list[EbayImage]
+    categories: list[EbayCategoryInfo]
+    buyingOptions: list[str]
+    shippingOptions: list[dict]
+    itemCreationDate: str
+    itemEndDate: str
+
+
+class EbayBrowseResponse(TypedDict, total=False):
+    """Full response of ``/buy/browse/v1/item_summary/search``."""
+
+    itemSummaries: list[EbayItemSummary]
+    total: int
+    next: str
+    limit: int
+    offset: int
+    warnings: list[dict]
+
+
+# --- Aggregated output for the GoupixDex internal API -----------------------
+
+
+GradedFilter = Literal["raw", "psa", "cgc", "bgs", "all"]
+ConditionFilter = Literal["new", "used", "all"]
+SortOrder = Literal["price_asc", "price_desc", "relevance", "newly_listed"]
+
+
+class MarketGradedInfo(TypedDict):
+    """Grading info extracted from item aspects (when present)."""
+
+    grader: str
+    grade: str
+
+
+class MarketStats(TypedDict):
+    """Aggregate price stats over the returned listings (EUR)."""
+
+    count: int
+    min: float | None
+    median: float | None
+    max: float | None
+    avg: float | None
+
+
+class MarketListing(TypedDict, total=False):
+    """Normalized listing returned to the frontend."""
+
+    item_id: str
+    title: str
+    price_eur: float
+    currency: str
+    condition: str
+    seller_username: str
+    seller_country: str
+    seller_feedback_score: int | None
+    image_url: str | None
+    listing_url: str
+    buying_options: list[str]
+    graded: NotRequired[MarketGradedInfo | None]
+
+
+class MarketSearchResponse(TypedDict):
+    """Top-level response from ``/ebay/market/search``."""
+
+    query: str
+    effective_query: str
+    marketplace_id: str
+    period_days: int
+    filters_applied: dict
+    stats: MarketStats
+    items: list[MarketListing]
+    outliers: list[MarketListing]
+    outliers_excluded: int
+    total_matches: int
+    warnings: list[str]

api/main.py

@@ -20,6 +20,7 @@
 from routes import access_requests as access_requests_routes
 from routes import articles as articles_routes
 from routes import auth as auth_routes
+from routes import ebay_market_route
 from routes import ebay_route
 from routes import pricing_route
 from routes import scan as scan_routes
@@ -101,6 +102,7 @@ def health() -> dict[str, str]:
 app.include_router(articles_routes.router)
 app.include_router(settings_route.router)
 app.include_router(ebay_route.router)
+app.include_router(ebay_market_route.router)
 app.include_router(pricing_route.router)
 app.include_router(stats_route.router)
 app.include_router(scan_routes.router)

api/routes/ebay_market_route.py

@@ -0,0 +1,147 @@
+"""Market price lookup on eBay France (public Browse API)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app_types.ebay_browse import (
+    ConditionFilter,
+    GradedFilter,
+    MarketSearchResponse,
+    SortOrder,
+)
+from config import get_settings
+from core.deps import get_current_user
+from models.user import User
+from services.ebay_app_oauth_service import ebay_app_oauth_configured
+from services.ebay_browse_service import DEFAULT_LIMIT, MAX_LIMIT, browse_search
+from services.ebay_price_aggregator_service import aggregate_prices, partition_outliers
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ebay/market", tags=["ebay-market"])
+
+#: Hardcoded noise-word list appended to every Browse query. These tokens
+#: describe **accessories** ("sleeve", "classeur", …) and are unlikely to
+#: appear in a user's legitimate sealed-product or card search.
+#:
+#: Negative tokens are forwarded to eBay as ``-"sleeve"`` so no matching
+#: listing is ever returned — this keeps noise out at the source without
+#: relying only on statistical outlier filtering.
+_DEFAULT_EXCLUDES: tuple[str, ...] = (
+    "sleeve",
+    "sleeves",
+    "protège-cartes",
+    "protege-cartes",
+    "protège carte",
+    "protege carte",
+    "étui",
+    "etui",
+    "classeur",
+    "portfolio",
+    "binder",
+    "album",
+    "intercalaire",
+    "divider",
+    "toploader",
+    "top loader",
+    "penny sleeve",
+    "playmat",
+    "tapis de jeu",
+    "boîte rangement",
+    "boite rangement",
+    "storage box",
+    "pin's",
+    "pin ",
+    "badge",
+    "sticker",
+    "autocollant",
+    "poster",
+    "affiche",
+    "plush",
+    "peluche",
+    "figurine",
+)
+
+
+@router.get("/search", response_model=None)
+async def search_market(
+    _user: Annotated[User, Depends(get_current_user)],
+    q: Annotated[str, Query(min_length=2, max_length=256)],
+    period_days: Annotated[int, Query(ge=0, le=365)] = 30,
+    condition: Annotated[ConditionFilter, Query()] = "new",
+    graded: Annotated[GradedFilter, Query()] = "all",
+    sort: Annotated[SortOrder, Query()] = "relevance",
+    fr_only: Annotated[bool, Query()] = False,
+    min_price: Annotated[float | None, Query(ge=0)] = None,
+    max_price: Annotated[float | None, Query(ge=0)] = None,
+    limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
+) -> MarketSearchResponse:
+    """
+    Search **active** eBay France listings matching ``q`` and return aggregated stats.
+
+    Authentication uses the OAuth Client Credentials flow (application token):
+    no user eBay connection required.
+
+    Noise-word exclusions (sleeves, étuis, classeurs, …) and statistical
+    outlier filtering are applied **server-side** by default — both are
+    relative to the median price, so legitimate low-value cards remain visible.
+    """
+    app = get_settings()
+    if not ebay_app_oauth_configured(app):
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="eBay app credentials not configured on the server (EBAY_CLIENT_ID, EBAY_CLIENT_SECRET).",
+        )
+    exclude_list = list(_DEFAULT_EXCLUDES)
+    try:
+        raw_listings, total, warnings, effective_q = await browse_search(
+            q=q.strip(),
+            period_days=period_days,
+            condition=condition,
+            graded=graded,
+            sort=sort,
+            min_price=min_price,
+            max_price=max_price,
+            fr_only=fr_only,
+            limit=limit,
+            exclude_keywords=exclude_list,
+            app=app,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    except Exception as exc:  # httpx raises HTTPStatusError etc.
+        logger.warning("eBay Browse search failed: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"eBay Browse API error: {exc}",
+        ) from exc
+
+    kept, outliers = partition_outliers(raw_listings)
+    stats = aggregate_prices(kept)
+    return {
+        "query": q.strip(),
+        "effective_query": effective_q,
+        "marketplace_id": "EBAY_FR",
+        "period_days": period_days,
+        "filters_applied": {
+            "condition": condition,
+            "graded": graded,
+            "sort": sort,
+            "fr_only": fr_only,
+            "min_price": min_price,
+            "max_price": max_price,
+            "limit": limit,
+            "exclude_keywords": exclude_list,
+            "exclude_outliers": True,
+        },
+        "stats": stats,
+        "items": kept,
+        "outliers": outliers,
+        "outliers_excluded": len(outliers),
+        "total_matches": total,
+        "warnings": warnings,
+    }

api/services/ebay_app_oauth_service.py

@@ -0,0 +1,104 @@
+"""
+eBay OAuth 2.0 **Client Credentials** flow (application token).
+
+Used for server-to-server APIs that don't need a user context, such as the
+public Browse API (``/buy/browse/v1``). The returned token is cached in-memory
+until close to expiry to avoid hammering the token endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import datetime as dt
+import logging
+from typing import Any
+
+import httpx
+
+from config import AppSettings, get_settings
+
+logger = logging.getLogger(__name__)
+
+#: Scope needed for the public Browse API (read-only marketplace search).
+BROWSE_API_SCOPE = "https://api.ebay.com/oauth/api_scope"
+
+#: Renew the token slightly before expiry to avoid mid-request invalidation.
+_EXPIRY_SKEW_SECONDS = 120
+
+_cached_token: str | None = None
+_cached_expires_at: dt.datetime | None = None
+_cache_lock = asyncio.Lock()
+
+
+def _token_url(app: AppSettings) -> str:
+    host = "api.sandbox.ebay.com" if app.ebay_use_sandbox else "api.ebay.com"
+    return f"https://{host}/identity/v1/oauth2/token"
+
+
+def _basic_auth_header(app: AppSettings) -> str:
+    raw = f"{(app.ebay_client_id or '').strip()}:{(app.ebay_client_secret or '').strip()}"
+    return base64.b64encode(raw.encode("utf-8")).decode("ascii")
+
+
+def ebay_app_oauth_configured(app: AppSettings | None = None) -> bool:
+    s = app or get_settings()
+    return bool((s.ebay_client_id or "").strip() and (s.ebay_client_secret or "").strip())
+
+
+async def _request_app_token(app: AppSettings) -> dict[str, Any]:
+    data = {"grant_type": "client_credentials", "scope": BROWSE_API_SCOPE}
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Authorization": f"Basic {_basic_auth_header(app)}",
+    }
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(_token_url(app), data=data, headers=headers)
+    if resp.status_code >= 400:
+        logger.warning(
+            "eBay app token request failed: %s %s",
+            resp.status_code,
+            resp.text[:500],
+        )
+        resp.raise_for_status()
+    return resp.json()
+
+
+async def get_app_access_token(*, app: AppSettings | None = None, force_refresh: bool = False) -> str:
+    """
+    Return a valid application access token for Browse API.
+
+    Caches the token across calls; refreshes a bit before its natural expiry.
+
+    Raises:
+        RuntimeError: if client id/secret are not configured in the environment.
+        httpx.HTTPStatusError: if eBay rejected the token request.
+    """
+    global _cached_token, _cached_expires_at  # noqa: PLW0603
+    s = app or get_settings()
+    if not ebay_app_oauth_configured(s):
+        raise RuntimeError(
+            "ebay_app_oauth_not_configured: set EBAY_CLIENT_ID and EBAY_CLIENT_SECRET in the environment.",
+        )
+    now = dt.datetime.now(dt.UTC)
+    if not force_refresh and _cached_token and _cached_expires_at and _cached_expires_at > now:
+        return _cached_token
+
+    async with _cache_lock:
+        if not force_refresh and _cached_token and _cached_expires_at and _cached_expires_at > now:
+            return _cached_token
+        payload = await _request_app_token(s)
+        access = str(payload.get("access_token") or "").strip()
+        if not access:
+            raise RuntimeError("eBay app token response is missing ``access_token``.")
+        expires_in = int(payload.get("expires_in") or 7200)
+        _cached_token = access
+        _cached_expires_at = now + dt.timedelta(seconds=max(60, expires_in - _EXPIRY_SKEW_SECONDS))
+        return access
+
+
+def invalidate_cached_app_token() -> None:
+    """Forget the cached token (useful after a 401)."""
+    global _cached_token, _cached_expires_at  # noqa: PLW0603
+    _cached_token = None
+    _cached_expires_at = None