robase-utils 2.3.0__py3-none-any.whl

roboat_utils/async_client.py

@@ -0,0 +1,481 @@
+"""
+roboat_utils.async_client
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Async version of RoboatClient using aiohttp.
+
+Bug fixes vs original:
+  - AsyncRoboatClient.__init__ accepted `cookie` param but stored nothing on error
+  - _handle used resp.ok which doesn't exist on aiohttp (use resp.status)
+  - All sub-API classes referenced undefined `Optional` without import
+  - get_servers used BASE (v1) but passed server_type in URL path — fixed
+  - get_user_games used BASE2 but the class only defined BASE — added BASE2
+
+Requires: pip install aiohttp
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+try:
+    import aiohttp
+    _AIOHTTP_AVAILABLE = True
+except ImportError:
+    _AIOHTTP_AVAILABLE = False
+
+from .models import (
+    User, Game, GameVotes, GameServer, Friend, Group, GroupRole,
+    Badge, CatalogItem, UserPresence, Avatar, RobuxBalance, Page,
+)
+from .exceptions import (
+    RateLimitedError, InvalidCookieError, UserNotFoundError,
+    GameNotFoundError, ItemNotFoundError, RoboatAPIError,
+    NotAuthenticatedError, raise_for_response,
+)
+
+
+class AsyncRoboatClient:
+    """
+    High-performance async Roblox API client using aiohttp.
+
+    Use as an async context manager::
+
+        async with AsyncRoboatClient(cookie="...") as client:
+            user = await client.users.get_user(156)
+
+            # Fan-out: fetch 1 000 users in parallel
+            user_ids = list(range(1, 1001))
+            users = await client.users.get_users_by_ids(user_ids)
+
+            # Parallel fetch with asyncio.gather
+            game, votes, icon = await asyncio.gather(
+                client.games.get_game(2753915549),
+                client.games.get_votes([2753915549]),
+                client.thumbnails.get_game_icons([2753915549]),
+            )
+
+    Or manage the session manually::
+
+        client = AsyncRoboatClient(cookie="...")
+        await client.start()
+        user = await client.users.get_user(156)
+        await client.close()
+    """
+
+    _BASE_HEADERS: Dict[str, str] = {
+        "Accept":       "application/json",
+        "Content-Type": "application/json",
+        "User-Agent":   "roboat-utils/3.0-async",
+    }
+
+    def __init__(self, cookie: Optional[str] = None, timeout: int = 10) -> None:
+        if not _AIOHTTP_AVAILABLE:
+            raise ImportError(
+                "aiohttp is required for AsyncRoboatClient. "
+                "Install it: pip install roboat-utils[async]"
+            )
+        self._cookie  = cookie
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._csrf_token: Optional[str] = None
+        self._session: Optional[aiohttp.ClientSession] = None
+
+        self.users      = _AsyncUsersAPI(self)
+        self.games      = _AsyncGamesAPI(self)
+        self.friends    = _AsyncFriendsAPI(self)
+        self.catalog    = _AsyncCatalogAPI(self)
+        self.groups     = _AsyncGroupsAPI(self)
+        self.thumbnails = _AsyncThumbnailsAPI(self)
+        self.badges     = _AsyncBadgesAPI(self)
+        self.presence   = _AsyncPresenceAPI(self)
+        self.economy    = _AsyncEconomyAPI(self)
+
+    # ── Lifecycle ─────────────────────────────────────────────────── #
+
+    async def start(self) -> None:
+        """Open the aiohttp session."""
+        cookies: Dict[str, str] = {}
+        if self._cookie:
+            cookies[".ROBLOSECURITY"] = self._cookie
+        self._session = aiohttp.ClientSession(
+            headers=self._BASE_HEADERS,
+            cookies=cookies,
+            timeout=self._timeout,
+        )
+        if self._cookie:
+            await self._refresh_csrf()
+
+    async def close(self) -> None:
+        """Close the aiohttp session."""
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> "AsyncRoboatClient":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    # ── Auth ──────────────────────────────────────────────────────── #
+
+    async def _refresh_csrf(self) -> None:
+        try:
+            async with self._session.post(          # type: ignore[union-attr]
+                "https://auth.roblox.com/v2/logout"
+            ) as r:
+                token = r.headers.get("x-csrf-token")
+                if token:
+                    self._csrf_token = token
+                    self._session.headers.update({"x-csrf-token": token})   # type: ignore[union-attr]
+        except Exception:
+            pass
+
+    def require_auth(self, method: str = "") -> None:
+        if not self._cookie:
+            raise NotAuthenticatedError(method)
+
+    # ── HTTP helpers ──────────────────────────────────────────────── #
+
+    async def _handle(self, resp: "aiohttp.ClientResponse") -> Any:
+        if resp.status == 403:
+            token = resp.headers.get("x-csrf-token")
+            if token and self._session:
+                self._csrf_token = token
+                self._session.headers.update({"x-csrf-token": token})
+            # caller will retry
+            return {}
+
+        if resp.status >= 400:
+            try:
+                body = await resp.json(content_type=None)
+            except Exception:
+                body = {}
+            raise_for_response(resp.status, body, url=str(resp.url))
+
+        try:
+            return await resp.json(content_type=None)
+        except Exception:
+            return {}
+
+    async def _get(self, url: str, **kwargs: Any) -> Any:
+        async with self._session.get(url, **kwargs) as r:   # type: ignore[union-attr]
+            return await self._handle(r)
+
+    async def _post(self, url: str, **kwargs: Any) -> Any:
+        async with self._session.post(url, **kwargs) as r:  # type: ignore[union-attr]
+            result = await self._handle(r)
+        if result == {} and r.status == 403:
+            async with self._session.post(url, **kwargs) as r2:  # type: ignore[union-attr]
+                return await self._handle(r2)
+        return result
+
+    # ── Convenience shortcuts ─────────────────────────────────────── #
+
+    async def user_id(self) -> int:
+        self.require_auth("user_id")
+        data = await self._get("https://users.roblox.com/v1/users/authenticated")
+        return data["id"]
+
+    async def username(self) -> str:
+        self.require_auth("username")
+        data = await self._get("https://users.roblox.com/v1/users/authenticated")
+        return data["name"]
+
+    async def robux(self) -> int:
+        self.require_auth("robux")
+        uid  = await self.user_id()
+        data = await self._get(f"https://economy.roblox.com/v1/users/{uid}/currency")
+        return data.get("robux", 0)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._cookie is not None
+
+    def __repr__(self) -> str:
+        auth = "authenticated" if self.is_authenticated else "unauthenticated"
+        return f"<AsyncRoboatClient [{auth}]>"
+
+
+# ── Sub-API implementations ───────────────────────────────────────── #
+
+class _AsyncUsersAPI:
+    BASE = "https://users.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_user(self, user_id: int) -> User:
+        data = await self._c._get(f"{self.BASE}/users/{user_id}")
+        return User.from_dict(data)
+
+    async def get_users_by_ids(
+        self, user_ids: List[int], exclude_banned: bool = False
+    ) -> List[User]:
+        results: List[User] = []
+        for i in range(0, len(user_ids), 100):
+            chunk = user_ids[i : i + 100]
+            data  = await self._c._post(
+                f"{self.BASE}/users",
+                json={"userIds": chunk, "excludeBannedUsers": exclude_banned},
+            )
+            results.extend(User.from_dict(u) for u in data.get("data", []))
+        return results
+
+    async def get_users_by_usernames(self, usernames: List[str]) -> List[User]:
+        data = await self._c._post(
+            f"{self.BASE}/usernames/users",
+            json={"usernames": usernames, "excludeBannedUsers": False},
+        )
+        return [User.from_dict(u) for u in data.get("data", [])]
+
+    async def search_users(self, keyword: str, limit: int = 10) -> Page:
+        data = await self._c._get(
+            f"{self.BASE}/users/search",
+            params={"keyword": keyword, "limit": limit},
+        )
+        return Page.from_dict(data, User)
+
+
+class _AsyncGamesAPI:
+    BASE  = "https://games.roblox.com/v1"
+    BASE2 = "https://games.roblox.com/v2"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_games(self, universe_ids: List[int]) -> List[Game]:
+        data = await self._c._get(
+            f"{self.BASE}/games",
+            params={"universeIds": ",".join(str(i) for i in universe_ids)},
+        )
+        return [Game.from_dict(g) for g in data.get("data", [])]
+
+    async def get_game(self, universe_id: int) -> Game:
+        games = await self.get_games([universe_id])
+        if not games:
+            raise GameNotFoundError(universe_id)
+        return games[0]
+
+    async def get_votes(self, universe_ids: List[int]) -> List[GameVotes]:
+        data = await self._c._get(
+            f"{self.BASE}/games/votes",
+            params={"universeIds": ",".join(str(i) for i in universe_ids)},
+        )
+        return [GameVotes.from_dict(v) for v in data.get("data", [])]
+
+    async def get_servers(
+        self, place_id: int, server_type: str = "Public", limit: int = 10
+    ) -> Page:
+        data = await self._c._get(
+            f"{self.BASE}/games/{place_id}/servers/{server_type}",
+            params={"limit": limit},
+        )
+        return Page(
+            data=[GameServer.from_dict(s) for s in data.get("data", [])],
+            next_cursor=data.get("nextPageCursor"),
+        )
+
+    async def get_user_games(self, user_id: int, limit: int = 50) -> Page:
+        data = await self._c._get(
+            f"{self.BASE2}/users/{user_id}/games",
+            params={"limit": limit},
+        )
+        return Page.from_dict(data, Game)
+
+
+class _AsyncFriendsAPI:
+    BASE = "https://friends.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_friends(self, user_id: int) -> List[Friend]:
+        data = await self._c._get(f"{self.BASE}/users/{user_id}/friends")
+        return [Friend.from_dict(f) for f in data.get("data", [])]
+
+    async def get_friend_count(self, user_id: int) -> int:
+        data = await self._c._get(f"{self.BASE}/users/{user_id}/friends/count")
+        return data.get("count", 0)
+
+    async def get_follower_count(self, user_id: int) -> int:
+        data = await self._c._get(f"{self.BASE}/users/{user_id}/followers/count")
+        return data.get("count", 0)
+
+    async def get_followers(
+        self, user_id: int, limit: int = 100, cursor: Optional[str] = None
+    ) -> Page:
+        params: Dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        data = await self._c._get(
+            f"{self.BASE}/users/{user_id}/followers", params=params
+        )
+        return Page.from_dict(data, Friend)
+
+
+class _AsyncCatalogAPI:
+    BASE = "https://catalog.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def search(
+        self,
+        keyword: str = "",
+        category: str = "All",
+        limit: int = 30,
+        cursor: Optional[str] = None,
+    ) -> Page:
+        params: Dict[str, Any] = {"category": category, "limit": limit}
+        if keyword:
+            params["keyword"] = keyword
+        if cursor:
+            params["cursor"] = cursor
+        data = await self._c._get(f"{self.BASE}/search/items", params=params)
+        return Page.from_dict(data, CatalogItem)
+
+    async def get_item_details(self, items: List[dict]) -> List[CatalogItem]:
+        data = await self._c._post(
+            f"{self.BASE}/catalog/items/details", json={"items": items}
+        )
+        return [CatalogItem.from_dict(i) for i in data.get("data", [])]
+
+
+class _AsyncGroupsAPI:
+    BASE = "https://groups.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_group(self, group_id: int) -> Group:
+        data = await self._c._get(f"{self.BASE}/groups/{group_id}")
+        return Group.from_dict(data)
+
+    async def get_roles(self, group_id: int) -> List[GroupRole]:
+        data = await self._c._get(f"{self.BASE}/groups/{group_id}/roles")
+        return [GroupRole.from_dict(r) for r in data.get("roles", [])]
+
+    async def get_members(
+        self, group_id: int, limit: int = 100, cursor: Optional[str] = None
+    ) -> Page:
+        params: Dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        data = await self._c._get(f"{self.BASE}/groups/{group_id}/users", params=params)
+        return Page.from_dict(data)
+
+
+class _AsyncThumbnailsAPI:
+    BASE = "https://thumbnails.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    def _urls(self, data: dict) -> Dict[int, str]:
+        return {
+            item["targetId"]: item.get("imageUrl", "")
+            for item in data.get("data", [])
+            if item.get("state") == "Completed"
+        }
+
+    async def get_user_avatars(
+        self, user_ids: List[int], size: str = "420x420"
+    ) -> Dict[int, str]:
+        data = await self._c._get(
+            f"{self.BASE}/users/avatar",
+            params={
+                "userIds": ",".join(str(i) for i in user_ids),
+                "size": size,
+                "format": "Png",
+            },
+        )
+        return self._urls(data)
+
+    async def get_game_icons(
+        self, universe_ids: List[int], size: str = "512x512"
+    ) -> Dict[int, str]:
+        data = await self._c._get(
+            f"{self.BASE}/games/icons",
+            params={
+                "universeIds": ",".join(str(i) for i in universe_ids),
+                "size": size,
+                "format": "Png",
+            },
+        )
+        return self._urls(data)
+
+    async def get_asset_thumbnails(
+        self, asset_ids: List[int], size: str = "420x420"
+    ) -> Dict[int, str]:
+        data = await self._c._get(
+            f"{self.BASE}/assets",
+            params={
+                "assetIds": ",".join(str(i) for i in asset_ids),
+                "size": size,
+                "format": "Png",
+            },
+        )
+        return self._urls(data)
+
+
+class _AsyncBadgesAPI:
+    BASE = "https://badges.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_badge(self, badge_id: int) -> Badge:
+        data = await self._c._get(f"{self.BASE}/badges/{badge_id}")
+        return Badge.from_dict(data)
+
+    async def get_universe_badges(self, universe_id: int, limit: int = 10) -> Page:
+        data = await self._c._get(
+            f"{self.BASE}/universes/{universe_id}/badges", params={"limit": limit}
+        )
+        return Page.from_dict(data, Badge)
+
+    async def get_user_badges(self, user_id: int, limit: int = 100) -> Page:
+        data = await self._c._get(
+            f"{self.BASE}/users/{user_id}/badges", params={"limit": limit}
+        )
+        return Page.from_dict(data, Badge)
+
+
+class _AsyncPresenceAPI:
+    BASE = "https://presence.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_presences(self, user_ids: List[int]) -> List[UserPresence]:
+        data = await self._c._post(
+            f"{self.BASE}/presence/users", json={"userIds": user_ids}
+        )
+        return [UserPresence.from_dict(p) for p in data.get("userPresences", [])]
+
+    async def get_presence(self, user_id: int) -> UserPresence:
+        results = await self.get_presences([user_id])
+        return results[0] if results else UserPresence(user_id=user_id)
+
+
+class _AsyncEconomyAPI:
+    BASE = "https://economy.roblox.com/v1"
+
+    def __init__(self, c: AsyncRoboatClient) -> None:
+        self._c = c
+
+    async def get_robux_balance(self, user_id: int) -> RobuxBalance:
+        self._c.require_auth("get_robux_balance")
+        data = await self._c._get(f"{self.BASE}/users/{user_id}/currency")
+        return RobuxBalance(robux=data.get("robux", 0))
+
+    async def get_asset_resale_data(self, asset_id: int) -> dict:
+        return await self._c._get(f"{self.BASE}/assets/{asset_id}/resale-data")
+
+    async def get_asset_resellers(self, asset_id: int, limit: int = 10) -> Page:
+        data = await self._c._get(
+            f"{self.BASE}/assets/{asset_id}/resellers", params={"limit": limit}
+        )
+        return Page.from_dict(data)

roboat_utils/avatar.py

@@ -0,0 +1,45 @@
+"""
+roboat.avatar
+~~~~~~~~~~~~~~~~
+Avatar API — avatar.roblox.com
+"""
+
+from roboat_utils.models import Avatar, Page
+
+
+class AvatarAPI:
+    BASE = "https://avatar.roblox.com/v1"
+    BASE2 = "https://avatar.roblox.com/v2"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_user_avatar(self, user_id: int) -> Avatar:
+        """Get the full avatar for a user."""
+        data = self._c._get(f"{self.BASE}/users/{user_id}/avatar")
+        return Avatar.from_dict(user_id, data)
+
+    def get_authenticated_avatar(self) -> Avatar:
+        """Get the authenticated user's avatar. Requires auth."""
+        self._c.require_auth("get_authenticated_avatar")
+        uid = self._c.users.get_authenticated_user()["id"]
+        data = self._c._get(f"{self.BASE}/avatar")
+        return Avatar.from_dict(uid, data)
+
+    def get_avatar_rules(self) -> dict:
+        """Get all avatar rules (allowed scales, asset types, etc.)."""
+        return self._c._get(f"{self.BASE}/avatar-rules")
+
+    def get_outfit(self, outfit_id: int) -> dict:
+        """Get details for a saved outfit."""
+        return self._c._get(f"{self.BASE}/outfits/{outfit_id}/details")
+
+    def get_user_outfits(self, user_id: int, page: int = 1,
+                         items_per_page: int = 25,
+                         is_editable: bool = False) -> dict:
+        """Get outfits for a user."""
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/outfits",
+            params={"page": page, "itemsPerPage": items_per_page,
+                    "isEditable": is_editable},
+        )

roboat_utils/badges.py

@@ -0,0 +1,50 @@
+"""
+roboat.badges
+~~~~~~~~~~~~~~~~
+Badges API — badges.roblox.com
+"""
+
+from typing import List, Optional
+from roboat_utils.models import Badge, Page
+
+
+class BadgesAPI:
+    BASE = "https://badges.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_badge(self, badge_id: int) -> Badge:
+        """Get badge info by ID."""
+        data = self._c._get(f"{self.BASE}/badges/{badge_id}")
+        return Badge.from_dict(data)
+
+    def get_universe_badges(self, universe_id: int, limit: int = 10,
+                            cursor: Optional[str] = None) -> Page:
+        """Get all badges for a universe/game."""
+        params = {"limit": limit, "sortOrder": "Asc"}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/universes/{universe_id}/badges", params=params)
+        return Page.from_dict(data, Badge)
+
+    def get_user_badges(self, user_id: int, limit: int = 10,
+                        cursor: Optional[str] = None) -> Page:
+        """Get badges awarded to a user."""
+        params = {"limit": limit, "sortOrder": "Asc"}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/users/{user_id}/badges", params=params)
+        return Page.from_dict(data, Badge)
+
+    def get_awarded_dates(self, user_id: int, badge_ids: List[int]) -> dict:
+        """
+        Check which badges a user has and when they were awarded.
+        Returns {badge_id: awarded_date_str}.
+        """
+        data = self._c._get(
+            f"{self.BASE}/users/{user_id}/badges/awarded-dates",
+            params={"badgeIds": ",".join(str(i) for i in badge_ids)},
+        )
+        return {
+            item["badgeId"]: item.get("awardedDate")
+            for item in data.get("data", [])
+        }

roboat_utils/catalog.py

@@ -0,0 +1,81 @@
+"""
+roboat.catalog
+~~~~~~~~~~~~~~~~~
+Catalog API — catalog.roblox.com
+"""
+
+from typing import List, Optional
+from roboat_utils.models import CatalogItem, Page
+
+
+class CatalogAPI:
+    BASE  = "https://catalog.roblox.com/v1"
+    BASE2 = "https://catalog.roblox.com/v2"
+
+    def __init__(self, client):
+        self._c = client
+
+    def search(self, keyword: str = "", category: str = "All",
+               subcategory: str = "All", sort_type: str = "Relevance",
+               price_min: Optional[int] = None, price_max: Optional[int] = None,
+               limit: int = 30, cursor: Optional[str] = None) -> Page:
+        """Search the avatar catalog."""
+        params = {
+            "category": category, "subcategory": subcategory,
+            "sortType": sort_type, "limit": limit,
+        }
+        if keyword:    params["keyword"] = keyword
+        if price_min:  params["minPrice"] = price_min
+        if price_max:  params["maxPrice"] = price_max
+        if cursor:     params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/search/items", params=params)
+        return Page.from_dict(data, CatalogItem)
+
+    def get_item_details(self, items: List[dict]) -> List[CatalogItem]:
+        """
+        Get details for catalog items.
+        items: list of {"itemType": "Asset"|"Bundle", "id": int}
+        """
+        data = self._c._post(
+            f"{self.BASE}/catalog/items/details",
+            json={"items": items},
+        )
+        return [CatalogItem.from_dict(i) for i in data.get("data", [])]
+
+    def get_asset(self, asset_id: int) -> CatalogItem:
+        """Get details for a single asset."""
+        results = self.get_item_details([{"itemType": "Asset", "id": asset_id}])
+        if not results:
+            from roboat_utils.exceptions import ItemNotFoundError
+            raise ItemNotFoundError(f"Asset {asset_id} not found")
+        return results[0]
+
+    def get_bundle(self, bundle_id: int) -> CatalogItem:
+        """Get details for a single bundle."""
+        results = self.get_item_details([{"itemType": "Bundle", "id": bundle_id}])
+        if not results:
+            from roboat_utils.exceptions import ItemNotFoundError
+            raise ItemNotFoundError(f"Bundle {bundle_id} not found")
+        return results[0]
+
+    def get_resale_data(self, asset_id: int):
+        """Get resale history for a limited item. Delegates to economy API."""
+        return self._c.economy.get_asset_resale_data(asset_id)
+
+    def get_resellers(self, asset_id: int, limit: int = 10,
+                      cursor: Optional[str] = None) -> Page:
+        """Get resellers for a limited item."""
+        return self._c.economy.get_asset_resellers(asset_id, limit, cursor)
+
+    def get_user_bundles(self, user_id: int, limit: int = 10,
+                         cursor: Optional[str] = None) -> Page:
+        """Get bundles owned by a user."""
+        params = {"limit": limit}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/users/{user_id}/bundles", params=params)
+        return Page.from_dict(data)
+
+    def get_asset_favorite_count(self, asset_id: int) -> int:
+        """Get favorite count for an asset."""
+        data = self._c._get(f"{self.BASE}/favorites/assets/{asset_id}/count")
+        return data if isinstance(data, int) else 0