rowrap 1.0.0__py3-none-any.whl

robloxapi/__init__.py

@@ -0,0 +1,22 @@
+"""
+robloxapi - A Python wrapper for the Roblox web APIs.
+
+Quickstart:
+    >>> from robloxapi import RobloxClient
+    >>> client = RobloxClient()                        # unauthenticated
+    >>> client = RobloxClient(cookie="ROBLOSECURITY")  # authenticated
+
+Sub-APIs:
+    client.users      - User lookups, search, username history
+    client.games      - Game details, visits, servers, votes, game page
+    client.catalog    - Item search, details, resale data, bundles
+    client.groups     - Group info, members, wall, audit log
+    client.friends    - Friends, followers, followings
+    client.thumbnails - Avatar, game, asset, group thumbnail URLs
+    client.badges     - Badge details, user badges, award dates
+"""
+
+from .client import RobloxClient
+
+__all__ = ["RobloxClient"]
+__version__ = "1.0.0"

robloxapi/badges.py

@@ -0,0 +1,83 @@
+"""
+Roblox Badges API - https://badges.roblox.com
+"""
+
+from typing import List, Optional
+
+
+class BadgesAPI:
+    BASE = "https://badges.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_badge(self, badge_id: int) -> dict:
+        """
+        Get badge info by ID.
+
+        Returns:
+            dict: {id, name, description, displayName, displayDescription,
+                   enabled, iconImageId, displayIconImageId, created,
+                   updated, statistics, awardingUniverse}
+        """
+        return self._c._get(f"{self.BASE}/badges/{badge_id}")
+
+    def get_universe_badges(self, universe_id: int, limit: int = 10,
+                            cursor: Optional[str] = None,
+                            sort_order: str = "Asc") -> dict:
+        """
+        Get all badges for a game/universe.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit, "sortOrder": sort_order}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE}/universes/{universe_id}/badges",
+            params=params,
+        )
+
+    def get_user_badges(self, user_id: int, limit: int = 10,
+                        cursor: Optional[str] = None,
+                        sort_order: str = "Asc") -> dict:
+        """
+        Get badges awarded to a user.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit, "sortOrder": sort_order}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/badges",
+            params=params,
+        )
+
+    def get_user_badges_by_game(self, user_id: int,
+                                universe_id: int) -> dict:
+        """
+        Get badges a user has earned in a specific game.
+
+        Returns:
+            dict: {data: [{badge, awardedDate}, ...]}
+        """
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/badges/awarded-dates",
+            params={"badgeIds": universe_id},
+        )
+
+    def get_badge_awarded_dates(self, user_id: int,
+                                badge_ids: List[int]) -> dict:
+        """
+        Check which badges a user has and when they were awarded.
+
+        Returns:
+            dict: {data: [{badgeId, awardedDate}, ...]}
+        """
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/badges/awarded-dates",
+            params={"badgeIds": ",".join(str(i) for i in badge_ids)},
+        )

robloxapi/catalog.py

@@ -0,0 +1,219 @@
+"""
+Roblox Catalog API - https://catalog.roblox.com
+Covers item search, item details, bundles, and resale data.
+"""
+
+from typing import List, Optional
+
+
+class CatalogAPI:
+    BASE = "https://catalog.roblox.com/v1"
+    BASE2 = "https://catalog.roblox.com/v2"
+
+    def __init__(self, client):
+        self._c = client
+
+    # ------------------------------------------------------------------ #
+    #  Search                                                              #
+    # ------------------------------------------------------------------ #
+
+    def search_catalog(
+        self,
+        keyword: str = "",
+        category: str = "All",
+        subcategory: str = "All",
+        sort_type: str = "Relevance",
+        sort_aggregation: int = 5,
+        price_min: Optional[int] = None,
+        price_max: Optional[int] = None,
+        limit: int = 30,
+        cursor: Optional[str] = None,
+        include_not_for_sale: bool = False,
+    ) -> dict:
+        """
+        Search the Roblox avatar shop / catalog.
+
+        Args:
+            category: "All", "Clothing", "Accessories", "AvatarAnimations",
+                      "BodyParts", "Gear", "Models", "Plugins", "Decals",
+                      "Audio", "Meshes", "Images", "MeshParts".
+            subcategory: Varies by category (e.g. "TShirts", "Hats").
+            sort_type: "Relevance", "Favorited", "Sales", "Updated",
+                       "PriceAsc", "PriceDesc".
+            sort_aggregation: Time window — 5=All time, 1=Past day, 3=Past week.
+            limit: 10, 28, 30, or 120.
+
+        Returns:
+            dict: {keyword, previousPageCursor, nextPageCursor,
+                   data: [{id, name, itemType, assetType, bundleType,
+                            description, productId, genres, bundledItems,
+                            itemStatus, itemRestrictions, creatorType,
+                            creatorTargetId, creatorName, price,
+                            premiumPricing, lowestPrice, purchaseCount,
+                            favoriteCount, offSaleDeadline}, ...]}
+        """
+        params = {
+            "category": category,
+            "subcategory": subcategory,
+            "sortType": sort_type,
+            "sortAggregation": sort_aggregation,
+            "limit": limit,
+            "includeNotForSale": include_not_for_sale,
+        }
+        if keyword:
+            params["keyword"] = keyword
+        if price_min is not None:
+            params["minPrice"] = price_min
+        if price_max is not None:
+            params["maxPrice"] = price_max
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(f"{self.BASE}/search/items", params=params)
+
+    # ------------------------------------------------------------------ #
+    #  Item details                                                        #
+    # ------------------------------------------------------------------ #
+
+    def get_item_details(self, items: List[dict]) -> dict:
+        """
+        Get details for multiple catalog items.
+
+        Args:
+            items: List of {itemType: "Asset"|"Bundle", id: int}
+
+        Returns:
+            dict: {data: [{id, itemType, assetType, name, description,
+                            productId, price, ...}, ...]}
+        """
+        return self._c._post(
+            f"{self.BASE}/catalog/items/details",
+            json={"items": items},
+        )
+
+    def get_asset_details(self, asset_id: int) -> dict:
+        """
+        Shortcut to get a single asset's details.
+        """
+        data = self.get_item_details([{"itemType": "Asset", "id": asset_id}])
+        results = data.get("data", [])
+        return results[0] if results else {}
+
+    def get_bundle_details(self, bundle_id: int) -> dict:
+        """
+        Get details of a specific bundle.
+
+        Returns:
+            dict: {id, name, description, bundleType, items, creator,
+                    product, ...}
+        """
+        return self._c._get(f"{self.BASE}/bundles/{bundle_id}/details")
+
+    def get_bundles_by_ids(self, bundle_ids: List[int]) -> dict:
+        """
+        Get multiple bundles by ID.
+
+        Returns:
+            dict: {data: [...]}
+        """
+        return self._c._get(
+            f"{self.BASE}/bundles/details",
+            params={"bundleIds": ",".join(str(i) for i in bundle_ids)},
+        )
+
+    # ------------------------------------------------------------------ #
+    #  User / group catalog                                                #
+    # ------------------------------------------------------------------ #
+
+    def get_user_bundles(self, user_id: int, bundle_type: Optional[str] = None,
+                         limit: int = 10, cursor: Optional[str] = None) -> dict:
+        """
+        Get bundles owned by a user.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit}
+        if bundle_type:
+            params["bundleType"] = bundle_type
+        if cursor:
+            params["cursor"] = cursor
+        url = (f"{self.BASE}/users/{user_id}/bundles"
+               if not bundle_type
+               else f"{self.BASE}/users/{user_id}/bundles/{bundle_type}")
+        return self._c._get(url, params=params)
+
+    def get_group_items(self, group_id: int, category: str = "2",
+                        limit: int = 30, cursor: Optional[str] = None) -> dict:
+        """
+        Get catalog items created by a group.
+
+        Args:
+            category: Asset category integer as string ("2" = clothing, etc.)
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"category": category, "limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE2}/search/items",
+            params={**params, "creatorType": "Group",
+                    "creatorTargetId": group_id},
+        )
+
+    # ------------------------------------------------------------------ #
+    #  Resale / economy                                                    #
+    # ------------------------------------------------------------------ #
+
+    def get_asset_resale_data(self, asset_id: int) -> dict:
+        """
+        Get resale price history and seller data for a limited item.
+
+        Returns:
+            dict: {assetStock, sales, numberRemaining, recentAveragePrice,
+                   originalPrice, priceDataPoints: [{value, date}],
+                   volumeDataPoints: [{value, date}]}
+        """
+        return self._c._get(
+            f"https://economy.roblox.com/v1/assets/{asset_id}/resale-data"
+        )
+
+    def get_asset_resellers(self, asset_id: int, limit: int = 10,
+                            cursor: Optional[str] = None) -> dict:
+        """
+        Get users currently reselling a limited item.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor,
+                   data: [{userAssetId, seller, price, serialNumber}, ...]}
+        """
+        params = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"https://economy.roblox.com/v1/assets/{asset_id}/resellers",
+            params=params,
+        )
+
+    # ------------------------------------------------------------------ #
+    #  Favorites                                                           #
+    # ------------------------------------------------------------------ #
+
+    def get_asset_favorite_count(self, asset_id: int) -> dict:
+        """
+        Get the number of users who have favorited an asset.
+
+        Returns:
+            int (the count)
+        """
+        resp = self._c._get(
+            f"{self.BASE}/favorites/assets/{asset_id}/count"
+        )
+        return resp
+
+    def get_bundle_favorite_count(self, bundle_id: int) -> dict:
+        """Get favorite count for a bundle."""
+        return self._c._get(
+            f"{self.BASE}/favorites/bundles/{bundle_id}/count"
+        )

robloxapi/client.py

@@ -0,0 +1,89 @@
+"""
+Roblox API Client - Main entry point for all API interactions.
+"""
+
+import requests
+from typing import Optional
+
+from .users import UsersAPI
+from .games import GamesAPI
+from .catalog import CatalogAPI
+from .groups import GroupsAPI
+from .friends import FriendsAPI
+from .thumbnails import ThumbnailsAPI
+from .badges import BadgesAPI
+
+
+class RobloxClient:
+    """
+    Main Roblox API client. Handles session management and provides
+    access to all sub-API modules.
+
+    Args:
+        cookie (str, optional): .ROBLOSECURITY cookie for authenticated requests.
+
+    Example:
+        >>> client = RobloxClient(cookie="YOUR_ROBLOSECURITY_COOKIE")
+        >>> user = client.users.get_user(1)
+        >>> print(user["name"])
+    """
+
+    BASE_HEADERS = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+    def __init__(self, cookie: Optional[str] = None):
+        self.session = requests.Session()
+        self.session.headers.update(self.BASE_HEADERS)
+        self._cookie = None
+        self._csrf_token = None
+
+        if cookie:
+            self.set_cookie(cookie)
+
+        # Initialize sub-APIs
+        self.users = UsersAPI(self)
+        self.games = GamesAPI(self)
+        self.catalog = CatalogAPI(self)
+        self.groups = GroupsAPI(self)
+        self.friends = FriendsAPI(self)
+        self.thumbnails = ThumbnailsAPI(self)
+        self.badges = BadgesAPI(self)
+
+    def set_cookie(self, cookie: str):
+        """Set the .ROBLOSECURITY authentication cookie."""
+        self._cookie = cookie
+        self.session.cookies.set(".ROBLOSECURITY", cookie, domain=".roblox.com")
+        self._refresh_csrf()
+
+    def _refresh_csrf(self):
+        """Fetch and store a fresh CSRF token."""
+        try:
+            resp = self.session.post("https://auth.roblox.com/v2/logout")
+            token = resp.headers.get("x-csrf-token")
+            if token:
+                self._csrf_token = token
+                self.session.headers.update({"x-csrf-token": token})
+        except Exception:
+            pass
+
+    def _get(self, url: str, **kwargs) -> dict:
+        """Perform a GET request and return JSON."""
+        resp = self.session.get(url, **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post(self, url: str, **kwargs) -> dict:
+        """Perform a POST request, refreshing CSRF on 403."""
+        resp = self.session.post(url, **kwargs)
+        if resp.status_code == 403:
+            self._refresh_csrf()
+            resp = self.session.post(url, **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Returns True if a cookie has been set."""
+        return self._cookie is not None

robloxapi/friends.py

@@ -0,0 +1,118 @@
+"""
+Roblox Friends API - https://friends.roblox.com
+"""
+
+from typing import Optional
+
+
+class FriendsAPI:
+    BASE = "https://friends.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_friends(self, user_id: int) -> dict:
+        """
+        Get a user's full friends list.
+
+        Returns:
+            dict: {data: [{id, name, displayName, hasVerifiedBadge,
+                            isOnline, presenceType, isDeleted,
+                            friendFrequentScore, friendFrequentRank}, ...]}
+        """
+        return self._c._get(f"{self.BASE}/users/{user_id}/friends")
+
+    def get_friend_count(self, user_id: int) -> dict:
+        """
+        Get the number of friends a user has.
+
+        Returns:
+            dict: {count}
+        """
+        return self._c._get(f"{self.BASE}/users/{user_id}/friends/count")
+
+    def get_followers(self, user_id: int, limit: int = 10,
+                      cursor: Optional[str] = None,
+                      sort_order: str = "Asc") -> dict:
+        """
+        Get users who follow a given user.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit, "sortOrder": sort_order}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/followers",
+            params=params,
+        )
+
+    def get_follower_count(self, user_id: int) -> dict:
+        """
+        Get the follower count for a user.
+
+        Returns:
+            dict: {count}
+        """
+        return self._c._get(f"{self.BASE}/users/{user_id}/followers/count")
+
+    def get_followings(self, user_id: int, limit: int = 10,
+                       cursor: Optional[str] = None,
+                       sort_order: str = "Asc") -> dict:
+        """
+        Get users that a given user follows.
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit, "sortOrder": sort_order}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE}/users/{user_id}/followings",
+            params=params,
+        )
+
+    def get_following_count(self, user_id: int) -> dict:
+        """
+        Get how many users a user is following.
+
+        Returns:
+            dict: {count}
+        """
+        return self._c._get(f"{self.BASE}/users/{user_id}/followings/count")
+
+    def get_friend_requests(self, limit: int = 10,
+                            cursor: Optional[str] = None) -> dict:
+        """
+        Get pending friend requests for the authenticated user (requires auth).
+
+        Returns:
+            dict: {previousPageCursor, nextPageCursor, data: [...]}
+        """
+        params = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"{self.BASE}/my/friends/requests",
+            params=params,
+        )
+
+    def get_friend_request_count(self) -> dict:
+        """
+        Get the number of pending friend requests (requires auth).
+
+        Returns:
+            dict: {count}
+        """
+        return self._c._get(f"{self.BASE}/user/friend-requests/count")
+
+    def are_friends(self, user_id: int) -> dict:
+        """
+        Check if the authenticated user is friends with user_id (requires auth).
+
+        Returns:
+            dict: {isFriend}
+        """
+        return self._c._get(f"{self.BASE}/users/{user_id}/friends/statuses")