Metadata-Version: 2.4
Name: rowrapee
Version: 1.21
Summary: A Python wrapper for the Roblox web APIs
License: MIT License
        
        Copyright (c) 2024
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/yourname/robloxapi
Project-URL: Repository, https://github.com/yourname/robloxapi
Keywords: roblox,api,wrapper
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# robloxapi

A clean Python wrapper around the public Roblox web APIs.

## Installation

```bash
pip install .
# or for development:
pip install -e .
```

**Requires:** Python 3.8+, `requests`

---

## Quickstart

```python
from robloxapi import RobloxClient

# Unauthenticated — works for all public endpoints
client = RobloxClient()

# Authenticated — required for inventory, friend requests, group management, etc.
client = RobloxClient(cookie="YOUR_.ROBLOSECURITY_COOKIE")
```

---

## API Reference

### 👤 Users — `client.users`

```python
# Get user by ID
user = client.users.get_user(1)
print(user["name"])  # "Roblox"

# Search users
results = client.users.search_users("builderman", limit=10)

# Bulk lookup by IDs or usernames
users = client.users.get_users_by_ids([1, 156])
users = client.users.get_users_by_usernames(["Roblox", "builderman"])

# Username history
history = client.users.get_username_history(156)

# Authenticated user
me = client.users.get_authenticated_user()
```

---

### 🎮 Games — `client.games`

```python
# Get game details (universe ID)
game = client.games.get_games([2753915549])
print(game["data"][0]["visits"])

# Get visit counts only
visits = client.games.get_game_visits([2753915549, 286090429])
# [{"universeId": 2753915549, "visits": 12345678}, ...]

# Resolve universe ID from place ID
info = client.games.get_game_by_place_id(6872265039)

# Games page (like Roblox home)
page = client.games.get_games_page(limit=10)

# Search games
results = client.games.search_games("obby", limit=20)

# Games by user / group
user_games = client.games.get_games_by_user(156)
group_games = client.games.get_games_by_group(2868472)

# Active servers for a place
servers = client.games.get_game_servers(place_id=6872265039, limit=10)

# Game passes
passes = client.games.get_game_passes(universe_id=2753915549)

# Votes
votes = client.games.get_game_votes([2753915549])

# Place details
places = client.games.get_place_details([6872265039])
```

---

### 🛍️ Catalog — `client.catalog`

```python
# Search the avatar shop
items = client.catalog.search_catalog(
    keyword="fedora",
    category="Accessories",
    sort_type="Sales",
    limit=30,
)

# Get item details
details = client.catalog.get_asset_details(asset_id=1028606)

# Multiple items at once
details = client.catalog.get_item_details([
    {"itemType": "Asset", "id": 1028606},
    {"itemType": "Bundle", "id": 192},
])

# Bundle details
bundle = client.catalog.get_bundle_details(192)

# Resale / limited item data
resale = client.catalog.get_asset_resale_data(asset_id=1028606)
sellers = client.catalog.get_asset_resellers(asset_id=1028606)
```

---

### 👥 Groups — `client.groups`

```python
# Group info
group = client.groups.get_group(2868472)

# Roles
roles = client.groups.get_group_roles(2868472)

# Members (all, or by role)
members = client.groups.get_group_members(2868472, limit=50)
members = client.groups.get_group_members(2868472, role_id=12345)

# Groups a user belongs to
user_groups = client.groups.get_user_groups(user_id=156)

# Search
results = client.groups.search_groups("builders")

# Wall
wall = client.groups.get_group_wall(2868472, limit=10)

# Funds (requires auth + perms)
funds = client.groups.get_group_funds(2868472)
```

---

### 🤝 Friends — `client.friends`

```python
# Friends list
friends = client.friends.get_friends(user_id=156)

# Counts
print(client.friends.get_friend_count(156)["count"])
print(client.friends.get_follower_count(156)["count"])
print(client.friends.get_following_count(156)["count"])

# Paginated followers / followings
followers  = client.friends.get_followers(156, limit=50)
followings = client.friends.get_followings(156, limit=50)

# Pending requests (requires auth)
requests = client.friends.get_friend_requests(limit=20)
```

---

### 🖼️ Thumbnails — `client.thumbnails`

```python
# Avatar thumbnails
thumbs = client.thumbnails.get_user_avatars([1, 156], size="420x420")
for t in thumbs["data"]:
    print(t["targetId"], t["imageUrl"])

# Headshots only
heads = client.thumbnails.get_user_avatar_headshots([1, 156])

# Game icons & screenshots
icons  = client.thumbnails.get_game_icons([2753915549])
shots  = client.thumbnails.get_game_thumbnails([2753915549], count_per_universe=3)

# Asset / bundle thumbnails
asset_thumbs  = client.thumbnails.get_asset_thumbnails([1028606])
bundle_thumbs = client.thumbnails.get_bundle_thumbnails([192])

# Group icons
group_icons = client.thumbnails.get_group_icons([2868472])
```

---

### 🏅 Badges — `client.badges`

```python
# Badge details
badge = client.badges.get_badge(2124445228)

# All badges in a game
badges = client.badges.get_universe_badges(universe_id=2753915549)

# Badges awarded to a user
user_badges = client.badges.get_user_badges(user_id=156)

# Which badges a user has (and when they got them)
dates = client.badges.get_badge_awarded_dates(
    user_id=156,
    badge_ids=[2124445228, 2124445229],
)
```

---

## Pagination helper

Most list endpoints return cursor-based pagination. Loop through pages like this:

```python
cursor = None
all_friends = []

while True:
    page = client.friends.get_followers(user_id=156, limit=100, cursor=cursor)
    all_friends.extend(page["data"])
    cursor = page.get("nextPageCursor")
    if not cursor:
        break

print(f"Total followers fetched: {len(all_friends)}")
```

---

## Authentication

Certain endpoints (friend requests, group funds, authenticated user info) require
a valid `.ROBLOSECURITY` cookie. You can obtain this from your browser's cookies
while logged into roblox.com.

> ⚠️ Never share your `.ROBLOSECURITY` cookie. Treat it like a password.

```python
client = RobloxClient(cookie="_|WARNING:-DO-NOT-SHARE-THIS-...")
me = client.users.get_authenticated_user()
```

---

## Error handling

All methods raise `requests.HTTPError` on non-2xx responses:

```python
from requests import HTTPError

try:
    user = client.users.get_user(99999999999)
except HTTPError as e:
    print(f"Error {e.response.status_code}: {e.response.text}")
```

---

## License

MIT
