feat(providers): add balldontlie http adapter with backend selection

apps/providers/adapters/balldontlie_provider.py

@@ -0,0 +1,147 @@
+import logging
+
+from django.conf import settings
+
+from apps.providers.clients import BalldontlieClient
+from apps.providers.interfaces import BaseProviderAdapter
+from apps.providers.services.balldontlie_mappings import (
+    map_competitions,
+    map_player_stats,
+    map_players,
+    map_seasons,
+    map_teams,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BalldontlieProviderAdapter(BaseProviderAdapter):
+    """HTTP MVP adapter for balldontlie (NBA-centric data source)."""
+
+    namespace = "balldontlie"
+
+    def __init__(self, client: BalldontlieClient | None = None):
+        self.client = client or BalldontlieClient()
+
+    @property
+    def configured_seasons(self) -> list[int]:
+        return settings.PROVIDER_BALLDONTLIE_SEASONS
+
+    def search_players(self, *, query: str = "", limit: int = 50, offset: int = 0) -> list[dict]:
+        params = {"search": query} if query else None
+        rows = self.client.list_paginated(
+            "players",
+            params=params,
+            per_page=min(limit, settings.PROVIDER_BALLDONTLIE_PLAYERS_PER_PAGE),
+            page_limit=1,
+        )
+        mapped = map_players(rows)
+        return mapped[offset : offset + limit]
+
+    def fetch_player(self, *, external_player_id: str) -> dict | None:
+        if not external_player_id.startswith("player-"):
+            return None
+        player_id = external_player_id.replace("player-", "", 1)
+        payload = self.client.get_json(f"players/{player_id}")
+        data = payload.get("data")
+        if not isinstance(data, dict):
+            return None
+        mapped = map_players([data])
+        return mapped[0] if mapped else None
+
+    def fetch_players(self) -> list[dict]:
+        rows = self.client.list_paginated(
+            "players",
+            per_page=settings.PROVIDER_BALLDONTLIE_PLAYERS_PER_PAGE,
+            page_limit=settings.PROVIDER_BALLDONTLIE_PLAYERS_PAGE_LIMIT,
+        )
+        return map_players(rows)
+
+    def fetch_competitions(self) -> list[dict]:
+        return map_competitions()
+
+    def fetch_teams(self) -> list[dict]:
+        payload = self.client.get_json("teams")
+        rows = payload.get("data") or []
+        return map_teams(rows if isinstance(rows, list) else [])
+
+    def fetch_seasons(self) -> list[dict]:
+        return map_seasons(self.configured_seasons)
+
+    def fetch_player_stats(self) -> list[dict]:
+        all_rows: list[dict] = []
+        for season in self.configured_seasons:
+            rows = self.client.list_paginated(
+                "stats",
+                params={"seasons[]": season},
+                per_page=settings.PROVIDER_BALLDONTLIE_STATS_PER_PAGE,
+                page_limit=settings.PROVIDER_BALLDONTLIE_STATS_PAGE_LIMIT,
+            )
+            all_rows.extend(rows)
+
+        player_stats, _ = map_player_stats(all_rows, allowed_seasons=self.configured_seasons)
+        return player_stats
+
+    def fetch_player_careers(self) -> list[dict]:
+        all_rows: list[dict] = []
+        for season in self.configured_seasons:
+            rows = self.client.list_paginated(
+                "stats",
+                params={"seasons[]": season},
+                per_page=settings.PROVIDER_BALLDONTLIE_STATS_PER_PAGE,
+                page_limit=settings.PROVIDER_BALLDONTLIE_STATS_PAGE_LIMIT,
+            )
+            all_rows.extend(rows)
+
+        _, player_careers = map_player_stats(all_rows, allowed_seasons=self.configured_seasons)
+        return player_careers
+
+    def sync_all(self) -> dict:
+        logger.info(
+            "provider_sync_start",
+            extra={"provider": self.namespace, "seasons": self.configured_seasons},
+        )
+        competitions = self.fetch_competitions()
+        teams = self.fetch_teams()
+        seasons = self.fetch_seasons()
+        players = self.fetch_players()
+
+        all_rows: list[dict] = []
+        for season in self.configured_seasons:
+            rows = self.client.list_paginated(
+                "stats",
+                params={"seasons[]": season},
+                per_page=settings.PROVIDER_BALLDONTLIE_STATS_PER_PAGE,
+                page_limit=settings.PROVIDER_BALLDONTLIE_STATS_PAGE_LIMIT,
+            )
+            all_rows.extend(rows)
+
+        player_stats, player_careers = map_player_stats(all_rows, allowed_seasons=self.configured_seasons)
+
+        logger.info(
+            "provider_sync_complete",
+            extra={
+                "provider": self.namespace,
+                "competitions": len(competitions),
+                "teams": len(teams),
+                "seasons": len(seasons),
+                "players": len(players),
+                "player_stats": len(player_stats),
+                "player_careers": len(player_careers),
+            },
+        )
+
+        return {
+            "players": players,
+            "competitions": competitions,
+            "teams": teams,
+            "seasons": seasons,
+            "player_stats": player_stats,
+            "player_careers": player_careers,
+            "cursor": None,
+        }
+
+    def sync_incremental(self, *, cursor: str | None = None) -> dict:
+        payload = self.sync_all()
+        payload["cursor"] = cursor
+        return payload