robase-utils 2.3.0__py3-none-any.whl

roboat_utils/inventory.py

@@ -0,0 +1,189 @@
+"""
+roboat.inventory
+~~~~~~~~~~~~~~~~~~~
+Inventory API — inventory.roblox.com + economy.roblox.com
+Check asset ownership, list user inventory, asset details.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import List, Optional
+from roboat_utils.models import Page
+
+
+@dataclass
+class InventoryAsset:
+    user_asset_id: int
+    asset_id: int
+    name: str
+    asset_type_id: int
+    created: str
+    updated: str
+    serial_number: Optional[int] = None
+    is_tradable: bool = False
+    is_recent_average_price_valid: bool = False
+    recent_average_price: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "InventoryAsset":
+        return cls(
+            user_asset_id=d.get("userAssetId", 0),
+            asset_id=d.get("assetId", 0),
+            name=d.get("name", ""),
+            asset_type_id=d.get("assetTypeId", 0),
+            created=d.get("created", ""),
+            updated=d.get("updated", ""),
+            serial_number=d.get("serialNumber"),
+            is_tradable=d.get("isTradable", False),
+            is_recent_average_price_valid=d.get("isRecentAveragePriceValid", False),
+            recent_average_price=d.get("recentAveragePrice", 0),
+        )
+
+    def __str__(self) -> str:
+        serial = f" #{self.serial_number}" if self.serial_number else ""
+        tradable = " [Tradable]" if self.is_tradable else ""
+        rap = f" RAP: {self.recent_average_price:,}R$" if self.recent_average_price else ""
+        return f"{self.name}{serial}{tradable}{rap}"
+
+
+class InventoryAPI:
+    BASE  = "https://inventory.roblox.com/v1"
+    BASE2 = "https://inventory.roblox.com/v2"
+    ECON  = "https://economy.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_user_inventory(self, user_id: int, asset_type_ids: List[int],
+                           limit: int = 100,
+                           cursor: Optional[str] = None) -> Page:
+        """
+        Get a user's inventory filtered by asset type.
+
+        Common asset_type_ids:
+            2  = T-Shirt       11 = Shirt       12 = Pants
+            8  = Hat           17 = Head        18 = Face
+            19 = Gear          25 = Body Parts   27 = Torso
+            28 = Right Arm     29 = Left Arm    30 = Right Leg
+            31 = Left Leg      41 = Hair        42 = Emote
+            43 = Shoulder      44 = Front       45 = Back
+            46 = Waist         47 = Climb       48 = Fall
+            49 = Jump          50 = Run         51 = Swim
+            52 = Walk          53 = Idle        54 = Animation
+            61 = Bundle        62 = AnimationBundle
+
+        Returns:
+            Page of InventoryAsset objects.
+        """
+        params = {
+            "assetTypeIds": ",".join(str(i) for i in asset_type_ids),
+            "limit": limit,
+            "sortOrder": "Asc",
+        }
+        if cursor:
+            params["cursor"] = cursor
+        data = self._c._get(
+            f"{self.BASE}/users/{user_id}/assets/collectibles",
+            params=params,
+        )
+        assets = [InventoryAsset.from_dict(a) for a in data.get("data", [])]
+        return Page(
+            data=assets,
+            next_cursor=data.get("nextPageCursor"),
+            previous_cursor=data.get("previousPageCursor"),
+        )
+
+    def get_collectibles(self, user_id: int, limit: int = 100,
+                         cursor: Optional[str] = None) -> Page:
+        """
+        Get all tradable/collectible (limited) items owned by a user.
+
+        Returns:
+            Page of InventoryAsset objects with RAP data.
+        """
+        params = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        data = self._c._get(
+            f"{self.BASE}/users/{user_id}/assets/collectibles",
+            params=params,
+        )
+        assets = [InventoryAsset.from_dict(a) for a in data.get("data", [])]
+        return Page(
+            data=assets,
+            next_cursor=data.get("nextPageCursor"),
+        )
+
+    def owns_asset(self, user_id: int, asset_id: int) -> bool:
+        """Check if a user owns a specific asset. Returns True/False."""
+        try:
+            data = self._c._get(
+                f"{self.BASE}/users/{user_id}/items/1/{asset_id}/is-owned"
+            )
+            return bool(data)
+        except Exception:
+            return False
+
+    def owns_badge(self, user_id: int, badge_id: int) -> bool:
+        """Check if a user has earned a specific badge."""
+        try:
+            data = self._c._get(
+                f"https://badges.roblox.com/v1/users/{user_id}/badges/awarded-dates",
+                params={"badgeIds": badge_id},
+            )
+            return len(data.get("data", [])) > 0
+        except Exception:
+            return False
+
+    def owns_game_pass(self, user_id: int, game_pass_id: int) -> bool:
+        """Check if a user owns a game pass."""
+        try:
+            data = self._c._get(
+                f"https://inventory.roblox.com/v1/users/{user_id}/items/GamePass/{game_pass_id}/is-owned"
+            )
+            return bool(data)
+        except Exception:
+            return False
+
+    def get_user_item_types(self, user_id: int) -> List[dict]:
+        """Get all item type categories available in a user's inventory."""
+        data = self._c._get(
+            f"{self.BASE2}/users/{user_id}/inventory",
+            params={"limit": 100},
+        )
+        return data.get("data", [])
+
+    def get_user_hats(self, user_id: int, limit: int = 100) -> Page:
+        """Shortcut: Get all hats owned by a user."""
+        return self.get_user_inventory(user_id, [8], limit=limit)
+
+    def get_user_faces(self, user_id: int, limit: int = 100) -> Page:
+        """Shortcut: Get all faces owned by a user."""
+        return self.get_user_inventory(user_id, [18], limit=limit)
+
+    def get_user_gear(self, user_id: int, limit: int = 100) -> Page:
+        """Shortcut: Get all gear owned by a user."""
+        return self.get_user_inventory(user_id, [19], limit=limit)
+
+    def get_user_clothes(self, user_id: int, limit: int = 100) -> Page:
+        """Shortcut: Get all clothing (shirt, pants, t-shirt) owned by a user."""
+        return self.get_user_inventory(user_id, [2, 11, 12], limit=limit)
+
+    def get_total_rap(self, user_id: int) -> int:
+        """
+        Calculate the total Recent Average Price (RAP) of a user's limiteds.
+        Iterates through all pages of collectibles.
+
+        Returns:
+            int: Total RAP in Robux.
+        """
+        total = 0
+        cursor = None
+        while True:
+            page = self.get_collectibles(user_id, limit=100, cursor=cursor)
+            for asset in page.data:
+                total += asset.recent_average_price
+            cursor = page.next_cursor
+            if not cursor:
+                break
+        return total

roboat_utils/marketplace.py

@@ -0,0 +1,279 @@
+"""
+roboat_utils.marketplace
+~~~~~~~~~~~~~~~~~~~~~~~~
+Marketplace tools — limited items, collectibles, UGC,
+purchase history, and economy monitoring.
+
+Example::
+
+    from roboat_utils.marketplace import MarketplaceAPI
+
+    market = MarketplaceAPI(client)
+    data   = market.get_limited_data(1365767)
+    print(data)
+
+    profit = market.estimate_resale_profit(1365767, purchase_price=5000)
+    print(profit)
+
+    tracker = market.create_rap_tracker([1365767, 1028606])
+    tracker.snapshot()
+    changes = tracker.diff()
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+import time
+
+
+@dataclass
+class LimitedData:
+    asset_id: int
+    name: str
+    asset_stock: Optional[int]
+    sales: int
+    number_remaining: Optional[int]
+    recent_average_price: int
+    original_price: Optional[int]
+    lowest_resale_price: Optional[int]
+    price_data_points: List[dict] = field(default_factory=list)
+    volume_data_points: List[dict] = field(default_factory=list)
+
+    @classmethod
+    def from_resale_dict(
+        cls, asset_id: int, resale: dict, details: Optional[dict] = None
+    ) -> "LimitedData":
+        return cls(
+            asset_id=asset_id,
+            name=details.get("name", "") if details else "",
+            asset_stock=resale.get("assetStock"),
+            sales=resale.get("sales", 0),
+            number_remaining=resale.get("numberRemaining"),
+            recent_average_price=resale.get("recentAveragePrice", 0),
+            original_price=resale.get("originalPrice"),
+            lowest_resale_price=None,
+            price_data_points=resale.get("priceDataPoints", []),
+            volume_data_points=resale.get("volumeDataPoints", []),
+        )
+
+    @property
+    def price_trend(self) -> str:
+        """'rising', 'falling', or 'stable' based on recent price history."""
+        points = [p["value"] for p in self.price_data_points[-5:] if "value" in p]
+        if len(points) < 2:
+            return "unknown"
+        delta = points[-1] - points[0]
+        if delta > points[0] * 0.05:
+            return "rising"
+        if delta < -(points[0] * 0.05):
+            return "falling"
+        return "stable"
+
+    def __str__(self) -> str:
+        remaining = f"{self.number_remaining:,}" if self.number_remaining is not None else "N/A"
+        low       = f"{self.lowest_resale_price:,}R$" if self.lowest_resale_price else "N/A"
+        emoji     = {"rising": "📈", "falling": "📉", "stable": "➡️", "unknown": "❓"}
+        return (
+            f"💎 {self.name} [#{self.asset_id}]\n"
+            f"   RAP       : {self.recent_average_price:,}R$\n"
+            f"   Lowest    : {low}\n"
+            f"   Sales     : {self.sales:,}\n"
+            f"   Remaining : {remaining}\n"
+            f"   Trend     : {emoji.get(self.price_trend, '❓')} {self.price_trend}"
+        )
+
+
+@dataclass
+class ResaleProfit:
+    asset_id: int
+    purchase_price: int
+    rap: int
+    lowest_resale: Optional[int]
+    roblox_fee: int
+    estimated_profit: int
+    roi_percent: float
+
+    def __str__(self) -> str:
+        sign = "+" if self.estimated_profit >= 0 else ""
+        return (
+            f"💰 Asset #{self.asset_id} Profit Estimate\n"
+            f"   Bought at  : {self.purchase_price:,}R$\n"
+            f"   RAP        : {self.rap:,}R$\n"
+            f"   Roblox fee : -{self.roblox_fee:,}R$ (30%)\n"
+            f"   Net profit : {sign}{self.estimated_profit:,}R$\n"
+            f"   ROI        : {self.roi_percent:+.1f}%"
+        )
+
+
+class RAPTracker:
+    """
+    Tracks RAP changes for a set of limited assets over time.
+
+    Usage::
+
+        tracker = RAPTracker(client, [1365767, 1028606])
+        tracker.snapshot()
+        # ... wait some time ...
+        print(tracker.summary())
+    """
+
+    def __init__(self, client, asset_ids: List[int]) -> None:
+        self._c = client
+        self.asset_ids = asset_ids
+        self._snapshots: List[Dict[int, int]] = []
+        self._timestamps: List[float] = []
+
+    def snapshot(self) -> Dict[int, int]:
+        """Take a RAP snapshot. Returns {asset_id: rap}."""
+        snap: Dict[int, int] = {}
+        for aid in self.asset_ids:
+            try:
+                data    = self._c._get(f"https://economy.roblox.com/v1/assets/{aid}/resale-data")
+                snap[aid] = data.get("recentAveragePrice", 0)
+            except Exception:
+                snap[aid] = 0
+        self._snapshots.append(snap)
+        self._timestamps.append(time.time())
+        return snap
+
+    def diff(self) -> List[dict]:
+        """Compare the last two snapshots."""
+        if len(self._snapshots) < 2:
+            return []
+        old, new = self._snapshots[-2], self._snapshots[-1]
+        results = []
+        for aid in self.asset_ids:
+            o     = old.get(aid, 0)
+            n     = new.get(aid, 0)
+            delta = n - o
+            pct   = ((delta / o) * 100) if o > 0 else 0.0
+            results.append({
+                "asset_id":   aid,
+                "old_rap":    o,
+                "new_rap":    n,
+                "change":     delta,
+                "change_pct": round(pct, 2),
+            })
+        return sorted(results, key=lambda x: abs(x["change"]), reverse=True)
+
+    def summary(self) -> str:
+        """Formatted summary of the latest diff."""
+        changes = self.diff()
+        if not changes:
+            return "No comparison data yet. Call snapshot() at least twice."
+        lines = ["📊 RAP Tracker Summary", "─" * 50]
+        for c in changes:
+            sign  = "+" if c["change"] >= 0 else ""
+            arrow = "↑" if c["change"] > 0 else ("↓" if c["change"] < 0 else "→")
+            lines.append(
+                f"  {arrow} Asset #{c['asset_id']:>12} "
+                f"| {c['old_rap']:>8,} → {c['new_rap']:>8,}R$ "
+                f"| {sign}{c['change']:,}R$ ({sign}{c['change_pct']}%)"
+            )
+        return "\n".join(lines)
+
+
+class MarketplaceAPI:
+    """
+    Marketplace tools for limited items, economy, and UGC.
+
+    Args:
+        client: A RoboatClient instance.
+    """
+
+    ECON = "https://economy.roblox.com/v1"
+    CAT  = "https://catalog.roblox.com/v1"
+
+    def __init__(self, client) -> None:
+        self._c = client
+
+    def get_limited_data(self, asset_id: int) -> LimitedData:
+        """Full resale data including price history and lowest listing."""
+        resale = self._c._get(f"{self.ECON}/assets/{asset_id}/resale-data")
+        try:
+            details_resp = self._c._post(
+                f"{self.CAT}/catalog/items/details",
+                json={"items": [{"itemType": "Asset", "id": asset_id}]},
+            )
+            details: Optional[dict] = details_resp.get("data", [{}])[0]
+        except Exception:
+            details = None
+
+        data = LimitedData.from_resale_dict(asset_id, resale, details)
+
+        try:
+            sellers = self._c._get(
+                f"{self.ECON}/assets/{asset_id}/resellers", params={"limit": 1}
+            )
+            first = sellers.get("data", [{}])[0]
+            data.lowest_resale_price = first.get("price")
+        except Exception:
+            pass
+
+        return data
+
+    def get_limited_data_bulk(self, asset_ids: List[int]) -> List[LimitedData]:
+        """Get limited data for multiple assets."""
+        return [self.get_limited_data(aid) for aid in asset_ids]
+
+    def estimate_resale_profit(self, asset_id: int, purchase_price: int) -> ResaleProfit:
+        """Estimate profit from reselling a limited (Roblox takes 30%)."""
+        data     = self.get_limited_data(asset_id)
+        sell_at  = data.lowest_resale_price or data.recent_average_price
+        fee      = int(sell_at * 0.30)
+        net      = sell_at - fee
+        profit   = net - purchase_price
+        roi      = ((profit / purchase_price) * 100) if purchase_price > 0 else 0.0
+        return ResaleProfit(
+            asset_id=asset_id,
+            purchase_price=purchase_price,
+            rap=data.recent_average_price,
+            lowest_resale=data.lowest_resale_price,
+            roblox_fee=fee,
+            estimated_profit=profit,
+            roi_percent=round(roi, 2),
+        )
+
+    def create_rap_tracker(self, asset_ids: List[int]) -> RAPTracker:
+        """Create a RAP tracker for a list of limited asset IDs."""
+        return RAPTracker(self._c, asset_ids)
+
+    def find_underpriced_limiteds(
+        self, asset_ids: List[int], threshold_pct: float = 0.85
+    ) -> List[LimitedData]:
+        """
+        Find limiteds currently selling below their RAP.
+
+        Returns items priced below *threshold_pct* × RAP, sorted by discount depth.
+        """
+        underpriced: List[LimitedData] = []
+        for aid in asset_ids:
+            try:
+                data = self.get_limited_data(aid)
+                if data.lowest_resale_price and data.recent_average_price:
+                    ratio = data.lowest_resale_price / data.recent_average_price
+                    if ratio < threshold_pct:
+                        underpriced.append(data)
+            except Exception:
+                continue
+        return sorted(
+            underpriced,
+            key=lambda d: (d.lowest_resale_price or 0) / max(d.recent_average_price, 1),
+        )
+
+    def get_user_purchase_history(
+        self,
+        user_id: int,
+        transaction_type: str = "Purchase",
+        limit: int = 25,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        """Get purchase history for a user. Requires auth."""
+        self._c.require_auth("get_user_purchase_history")
+        params: dict = {"transactionType": transaction_type, "limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._c._get(
+            f"https://economy.roblox.com/v2/users/{user_id}/transactions",
+            params=params,
+        )

roboat_utils/messages.py

@@ -0,0 +1,194 @@
+"""
+roboat.messages
+~~~~~~~~~~~~~~~~~~
+Private Messages API — privatemessages.roblox.com
+All endpoints require authentication.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List, Optional
+from roboat_utils.models import Page
+
+
+@dataclass
+class Message:
+    id: int
+    sender_id: int
+    sender_name: str
+    recipient_id: int
+    recipient_name: str
+    subject: str
+    body: str
+    created: str
+    updated: str
+    is_read: bool
+    is_system_message: bool
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Message":
+        sender = d.get("sender", {})
+        recipient = d.get("recipient", {})
+        return cls(
+            id=d.get("id", 0),
+            sender_id=sender.get("id", 0),
+            sender_name=sender.get("name", ""),
+            recipient_id=recipient.get("id", 0),
+            recipient_name=recipient.get("name", ""),
+            subject=d.get("subject", ""),
+            body=d.get("body", ""),
+            created=d.get("created", ""),
+            updated=d.get("updated", ""),
+            is_read=d.get("isRead", False),
+            is_system_message=d.get("isSystemMessage", False),
+        )
+
+    def __str__(self) -> str:
+        read = "📬" if not self.is_read else "📭"
+        return f"{read} [{self.id}] From: {self.sender_name} | {self.subject}"
+
+
+class MessagesAPI:
+    BASE = "https://privatemessages.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_messages(self, message_type: str = "Inbox",
+                     page_size: int = 25, page_number: int = 0) -> Page:
+        """
+        Get private messages. Requires auth.
+
+        Args:
+            message_type: "Inbox", "Sent", "Archive"
+            page_size: 10, 20, 25
+            page_number: Zero-indexed page number.
+
+        Returns:
+            Page of Message objects.
+        """
+        self._c.require_auth("get_messages")
+        data = self._c._get(
+            f"{self.BASE}/messages",
+            params={
+                "messageTab": message_type,
+                "pageSize": page_size,
+                "pageNumber": page_number,
+            },
+        )
+        messages = [Message.from_dict(m) for m in data.get("collection", [])]
+        return Page(data=messages)
+
+    def get_message(self, message_id: int) -> Message:
+        """Get a single message by ID. Requires auth."""
+        self._c.require_auth("get_message")
+        data = self._c._get(f"{self.BASE}/messages/{message_id}")
+        return Message.from_dict(data)
+
+    def send_message(self, recipient_id: int, subject: str, body: str) -> dict:
+        """Send a private message. Requires auth."""
+        self._c.require_auth("send_message")
+        return self._c._post(
+            f"{self.BASE}/messages/send",
+            json={
+                "recipientId": recipient_id,
+                "subject": subject,
+                "body": body,
+            },
+        )
+
+    def get_unread_count(self) -> int:
+        """Get count of unread messages. Requires auth."""
+        self._c.require_auth("get_unread_count")
+        data = self._c._get(f"{self.BASE}/messages/unread/count")
+        return data.get("count", 0)
+
+    def mark_read(self, message_ids: List[int]) -> None:
+        """Mark messages as read. Requires auth."""
+        self._c.require_auth("mark_read")
+        self._c._post(
+            f"{self.BASE}/messages/mark-read",
+            json={"messageIds": message_ids},
+        )
+
+    def mark_unread(self, message_ids: List[int]) -> None:
+        """Mark messages as unread. Requires auth."""
+        self._c.require_auth("mark_unread")
+        self._c._post(
+            f"{self.BASE}/messages/mark-unread",
+            json={"messageIds": message_ids},
+        )
+
+    def archive(self, message_ids: List[int]) -> None:
+        """Archive messages. Requires auth."""
+        self._c.require_auth("archive")
+        self._c._post(
+            f"{self.BASE}/messages/archive",
+            json={"messageIds": message_ids},
+        )
+
+
+@dataclass
+class ChatConversation:
+    id: int
+    title: str
+    conversation_type: str
+    participants: List[dict] = field(default_factory=list)
+    last_updated: Optional[str] = None
+    unread_count: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ChatConversation":
+        return cls(
+            id=d.get("id", 0),
+            title=d.get("title", ""),
+            conversation_type=d.get("conversationType", ""),
+            participants=d.get("participants", []),
+            last_updated=d.get("lastUpdated"),
+            unread_count=d.get("unreadMessageCount", 0),
+        )
+
+    def __str__(self) -> str:
+        unread = f" [{self.unread_count} unread]" if self.unread_count else ""
+        return f"💬 {self.title}{unread}"
+
+
+class ChatAPI:
+    BASE = "https://chat.roblox.com/v2"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_conversations(self, page_size: int = 30,
+                          page_number: int = 1) -> List[ChatConversation]:
+        """Get chat conversations. Requires auth."""
+        self._c.require_auth("get_conversations")
+        data = self._c._get(
+            f"{self.BASE}/get-user-conversations",
+            params={"pageSize": page_size, "pageNumber": page_number},
+        )
+        return [ChatConversation.from_dict(c) for c in (data if isinstance(data, list) else [])]
+
+    def get_unread_conversation_count(self) -> int:
+        """Get count of conversations with unread messages. Requires auth."""
+        self._c.require_auth("get_unread_conversation_count")
+        data = self._c._get(f"{self.BASE}/get-unread-conversation-count")
+        return data.get("count", 0)
+
+    def get_messages(self, conversation_id: int,
+                     page_size: int = 30) -> list:
+        """Get messages in a conversation. Requires auth."""
+        self._c.require_auth("get_messages")
+        data = self._c._get(
+            f"{self.BASE}/get-messages",
+            params={"conversationId": conversation_id, "pageSize": page_size},
+        )
+        return data if isinstance(data, list) else []
+
+    def send_message(self, conversation_id: int, message: str) -> dict:
+        """Send a chat message. Requires auth."""
+        self._c.require_auth("send_message")
+        return self._c._post(
+            f"{self.BASE}/send-message",
+            json={"conversationId": conversation_id, "message": message},
+        )