robase-utils 2.3.0__py3-none-any.whl

roboat_utils/events.py

@@ -0,0 +1,259 @@
+"""
+roboat.events
+~~~~~~~~~~~~~~~~
+Polling-based event system.
+Monitor friends coming online, new game visits, friend requests, etc.
+
+Example::
+
+    from roboat import RoboatClient
+    from roboat_utils.events import EventPoller
+
+    client = RoboatClient(cookie="...")
+    poller = EventPoller(client)
+
+    @poller.on_friend_online
+    def handle(user):
+        print(f"{user.name} just came online!")
+
+    @poller.on_visit_milestone
+    def milestone(game, count):
+        print(f"{game.name} just hit {count:,} visits!")
+
+    poller.start(interval=30)  # poll every 30 seconds
+"""
+
+from __future__ import annotations
+import threading
+import time
+from typing import Callable, Dict, List, Optional, Set
+
+
+class EventPoller:
+    """
+    Background polling engine that fires callbacks when Roblox state changes.
+
+    Args:
+        client: An authenticated RoboatClient.
+        interval: Polling interval in seconds (default: 30).
+
+    Registering handlers::
+
+        @poller.on("friend_online")
+        def handler(user):
+            print(user.name, "is online!")
+
+    Starting / stopping::
+
+        poller.start()         # background thread
+        poller.stop()
+        poller.run_once()      # manual single poll
+    """
+
+    def __init__(self, client, interval: float = 30.0):
+        self._c = client
+        self.interval = interval
+        self._handlers: Dict[str, List[Callable]] = {}
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+        # State tracking
+        self._known_friends: Set[int] = set()
+        self._known_online: Set[int] = set()
+        self._tracked_universes: Dict[int, int] = {}  # universe_id → last visit count
+        self._visit_milestones: Dict[int, int] = {}   # universe_id → next milestone
+        self._known_requests: Set[int] = set()
+        self._last_message_count: int = -1
+
+    # ── Registration decorators ───────────────────────────────────────
+
+    def on(self, event: str) -> Callable:
+        """Generic decorator: @poller.on("event_name")"""
+        def decorator(fn: Callable) -> Callable:
+            self._handlers.setdefault(event, []).append(fn)
+            return fn
+        return decorator
+
+    @property
+    def on_friend_online(self) -> Callable:
+        """Fires when a friend comes online. Handler receives (User,)."""
+        return self.on("friend_online")
+
+    @property
+    def on_friend_offline(self) -> Callable:
+        """Fires when a friend goes offline. Handler receives (User,)."""
+        return self.on("friend_offline")
+
+    @property
+    def on_new_friend(self) -> Callable:
+        """Fires when you gain a new friend. Handler receives (User,)."""
+        return self.on("new_friend")
+
+    @property
+    def on_friend_removed(self) -> Callable:
+        """Fires when a friend is removed. Handler receives (user_id,)."""
+        return self.on("friend_removed")
+
+    @property
+    def on_friend_request(self) -> Callable:
+        """Fires on new friend request. Handler receives (User,)."""
+        return self.on("friend_request")
+
+    @property
+    def on_new_message(self) -> Callable:
+        """Fires when an unread message count increases. Handler receives (count,)."""
+        return self.on("new_message")
+
+    @property
+    def on_visit_milestone(self) -> Callable:
+        """
+        Fires when a tracked game hits a visit milestone.
+        Handler receives (Game, milestone_count).
+        """
+        return self.on("visit_milestone")
+
+    # ── Game tracking ─────────────────────────────────────────────────
+
+    def track_game(self, universe_id: int,
+                   milestone_step: int = 1_000_000) -> None:
+        """
+        Add a universe to visit monitoring.
+
+        Args:
+            universe_id: The universe to watch.
+            milestone_step: Fire an event every N visits (default: 1M).
+        """
+        self._tracked_universes[universe_id] = 0
+        self._visit_milestones[universe_id] = milestone_step
+
+    def untrack_game(self, universe_id: int) -> None:
+        """Stop watching a universe for visit milestones."""
+        self._tracked_universes.pop(universe_id, None)
+        self._visit_milestones.pop(universe_id, None)
+
+    # ── Control ───────────────────────────────────────────────────────
+
+    def start(self, interval: Optional[float] = None, daemon: bool = True) -> None:
+        """
+        Start polling in a background thread.
+
+        Args:
+            interval: Override polling interval.
+            daemon: If True, thread exits when main program exits.
+        """
+        if interval is not None:
+            self.interval = interval
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=daemon)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the background polling thread."""
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+
+    def run_once(self) -> None:
+        """Run a single poll cycle (useful for testing or manual control)."""
+        self._poll()
+
+    def _loop(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                self._poll()
+            except Exception:
+                pass
+            self._stop_event.wait(self.interval)
+
+    # ── Poll logic ────────────────────────────────────────────────────
+
+    def _fire(self, event: str, *args) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                handler(*args)
+            except Exception:
+                pass
+
+    def _poll(self) -> None:
+        self._poll_friends()
+        self._poll_games()
+        self._poll_messages()
+
+    def _poll_friends(self) -> None:
+        if not self._c.is_authenticated:
+            return
+        try:
+            uid = self._c.user_id()
+            friends = self._c.friends.get_friends(uid)
+            current_ids = {f.id for f in friends}
+
+            # New friends
+            for f in friends:
+                if f.id not in self._known_friends and self._known_friends:
+                    self._fire("new_friend", f)
+
+            # Removed friends
+            for fid in (self._known_friends - current_ids):
+                self._fire("friend_removed", fid)
+
+            self._known_friends = current_ids
+
+            # Online status
+            if friends:
+                presences = self._c.presence.get_presences(list(current_ids)[:50])
+                current_online = {
+                    p.user_id for p in presences if p.user_presence_type > 0
+                }
+                friend_map = {f.id: f for f in friends}
+
+                for uid_p in (current_online - self._known_online):
+                    if uid_p in friend_map:
+                        self._fire("friend_online", friend_map[uid_p])
+
+                for uid_p in (self._known_online - current_online):
+                    if uid_p in friend_map:
+                        self._fire("friend_offline", friend_map[uid_p])
+
+                self._known_online = current_online
+
+            # Friend requests
+            requests_page = self._c.friends.get_friend_requests(limit=10)
+            current_requests = {u.id for u in requests_page.data}
+            for user in requests_page.data:
+                if user.id not in self._known_requests and self._known_requests:
+                    self._fire("friend_request", user)
+            self._known_requests = current_requests
+
+        except Exception:
+            pass
+
+    def _poll_games(self) -> None:
+        if not self._tracked_universes:
+            return
+        try:
+            ids = list(self._tracked_universes.keys())
+            games = self._c.games.get_games(ids)
+            for game in games:
+                last = self._tracked_universes.get(game.id, 0)
+                step = self._visit_milestones.get(game.id, 1_000_000)
+                if last == 0:
+                    self._tracked_universes[game.id] = game.visits
+                    continue
+                next_milestone = (last // step + 1) * step
+                if game.visits >= next_milestone:
+                    self._fire("visit_milestone", game, next_milestone)
+                self._tracked_universes[game.id] = game.visits
+        except Exception:
+            pass
+
+    def _poll_messages(self) -> None:
+        if not self._c.is_authenticated:
+            return
+        try:
+            count = self._c.messages.get_unread_count()
+            if self._last_message_count >= 0 and count > self._last_message_count:
+                self._fire("new_message", count)
+            self._last_message_count = count
+        except Exception:
+            pass

roboat_utils/exceptions.py

@@ -0,0 +1,221 @@
+"""
+roboat_utils.exceptions
+~~~~~~~~~~~~~~~~~~~~~~~
+Exception hierarchy for roboat-utils.
+
+Hierarchy
+---------
+RoboatAPIError
+├── HTTPError
+│   ├── RateLimitedError      (429)  — has .retry_after
+│   ├── InvalidCookieError    (401)
+│   ├── ForbiddenError        (403)
+│   ├── NotFoundError         (404)
+│   │   ├── UserNotFoundError
+│   │   ├── GameNotFoundError
+│   │   ├── ItemNotFoundError
+│   │   ├── GroupNotFoundError
+│   │   └── BadgeNotFoundError
+│   └── ServerError           (5xx)
+├── NotAuthenticatedError
+├── InsufficientFundsError
+└── DatabaseError
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+
+class RoboatAPIError(Exception):
+    """Base class for all roboat-utils exceptions."""
+
+    def __init__(self, message: str = "", *, errors: list | None = None) -> None:
+        self.errors: list = errors or []
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.args[0]!r})"
+
+
+# ── HTTP layer ──────────────────────────────────────────────────────── #
+
+class HTTPError(RoboatAPIError):
+    """Raised for non-2xx HTTP responses from the Roblox API."""
+
+    def __init__(self, status_code: int, message: str = "",
+                 *, errors: list | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(f"HTTP {status_code}: {message}", errors=errors)
+
+    @property
+    def is_retryable(self) -> bool:
+        return self.status_code in (429, 500, 502, 503, 504)
+
+
+class RateLimitedError(HTTPError):
+    """HTTP 429 — rate limit exceeded."""
+
+    def __init__(self, retry_after: Optional[float] = None) -> None:
+        self.retry_after = retry_after
+        msg = "Rate limited by Roblox API."
+        if retry_after:
+            msg += f" Retry after {retry_after:.1f}s."
+        super().__init__(429, msg)
+
+
+class InvalidCookieError(HTTPError):
+    """HTTP 401 — the .ROBLOSECURITY cookie is invalid or expired."""
+
+    def __init__(self) -> None:
+        super().__init__(401, "Invalid or expired .ROBLOSECURITY cookie.")
+
+
+class ForbiddenError(HTTPError):
+    """HTTP 403 — insufficient permissions."""
+
+    def __init__(self, message: str = "Forbidden.") -> None:
+        super().__init__(403, message)
+
+
+class NotFoundError(HTTPError):
+    """HTTP 404 — resource not found."""
+
+    def __init__(self, message: str = "Resource not found.") -> None:
+        super().__init__(404, message)
+
+
+class ServerError(HTTPError):
+    """HTTP 5xx — Roblox-side server error."""
+
+    def __init__(self, status_code: int, message: str = "") -> None:
+        super().__init__(status_code, message or f"Server error ({status_code}).")
+
+
+# ── Not-found specialisations ────────────────────────────────────────── #
+
+class UserNotFoundError(NotFoundError):
+    """Raised when a user cannot be found by ID or username."""
+
+    def __init__(self, identifier: int | str = "") -> None:
+        super().__init__(f"User not found: {identifier!r}")
+        self.identifier = identifier
+
+
+class GameNotFoundError(NotFoundError):
+    """Raised when a universe/place cannot be found."""
+
+    def __init__(self, universe_id: int | str = "") -> None:
+        super().__init__(f"Game not found: universe {universe_id!r}")
+        self.universe_id = universe_id
+
+
+class ItemNotFoundError(NotFoundError):
+    """Raised when a catalog item cannot be found."""
+
+    def __init__(self, asset_id: int | str = "") -> None:
+        super().__init__(f"Catalog item not found: {asset_id!r}")
+        self.asset_id = asset_id
+
+
+class GroupNotFoundError(NotFoundError):
+    """Raised when a group cannot be found."""
+
+    def __init__(self, group_id: int | str = "") -> None:
+        super().__init__(f"Group not found: {group_id!r}")
+        self.group_id = group_id
+
+
+class BadgeNotFoundError(NotFoundError):
+    """Raised when a badge cannot be found."""
+
+    def __init__(self, badge_id: int | str = "") -> None:
+        super().__init__(f"Badge not found: {badge_id!r}")
+        self.badge_id = badge_id
+
+
+# ── Logic exceptions ─────────────────────────────────────────────────── #
+
+class NotAuthenticatedError(RoboatAPIError):
+    """Raised when a method requires authentication but none is set."""
+
+    def __init__(self, method: str = "") -> None:
+        where = f" ({method})" if method else ""
+        super().__init__(
+            f"Authentication required{where}. "
+            "Pass a .ROBLOSECURITY cookie to RoboatClient."
+        )
+
+
+class InsufficientFundsError(RoboatAPIError):
+    """Raised when a purchase cannot be completed due to insufficient Robux."""
+
+    def __init__(self, required: int = 0, available: int = 0) -> None:
+        msg = "Insufficient Robux."
+        if required and available:
+            msg = f"Need {required:,}R$ but only have {available:,}R$."
+        super().__init__(msg)
+        self.required = required
+        self.available = available
+
+
+class DatabaseError(RoboatAPIError):
+    """Raised for errors relating to the local session database."""
+
+
+# ── Helper ────────────────────────────────────────────────────────────── #
+
+def raise_for_response(status_code: int, body: dict, url: str = "") -> None:
+    """
+    Parse a Roblox API response and raise the appropriate exception.
+
+    Args:
+        status_code: HTTP status code.
+        body: Parsed JSON response body.
+        url: Request URL (used to pick a more specific Not-Found subclass).
+    """
+    if 200 <= status_code < 300:
+        return
+
+    # Extract Roblox error message
+    errs = body.get("errors", [])
+    msg = "; ".join(e.get("message", "") for e in errs if e.get("message"))
+    if not msg:
+        msg = body.get("message", "")
+
+    if status_code == 401:
+        raise InvalidCookieError()
+    if status_code == 429:
+        raise RateLimitedError()
+    if status_code == 403:
+        raise ForbiddenError(msg or "Forbidden.")
+    if status_code == 404:
+        url_lower = url.lower()
+        if "users"   in url_lower: raise UserNotFoundError(msg or url)
+        if "games"   in url_lower: raise GameNotFoundError(msg or url)
+        if "catalog" in url_lower: raise ItemNotFoundError(msg or url)
+        if "groups"  in url_lower: raise GroupNotFoundError(msg or url)
+        if "badges"  in url_lower: raise BadgeNotFoundError(msg or url)
+        raise NotFoundError(msg or f"Not found: {url}")
+    if status_code >= 500:
+        raise ServerError(status_code, msg)
+    raise HTTPError(status_code, msg, errors=errs)
+
+
+__all__ = [
+    "RoboatAPIError",
+    "HTTPError",
+    "RateLimitedError",
+    "InvalidCookieError",
+    "ForbiddenError",
+    "NotFoundError",
+    "UserNotFoundError",
+    "GameNotFoundError",
+    "ItemNotFoundError",
+    "GroupNotFoundError",
+    "BadgeNotFoundError",
+    "ServerError",
+    "NotAuthenticatedError",
+    "InsufficientFundsError",
+    "DatabaseError",
+    "raise_for_response",
+]

roboat_utils/friends.py

@@ -0,0 +1,80 @@
+"""
+roboat.friends
+~~~~~~~~~~~~~~~~~
+Friends API — friends.roblox.com
+"""
+
+from typing import Optional, List
+from roboat_utils.models import Friend, Page
+
+
+class FriendsAPI:
+    BASE = "https://friends.roblox.com/v1"
+
+    def __init__(self, client):
+        self._c = client
+
+    def get_friends(self, user_id: int) -> List[Friend]:
+        """Get the full friends list for a user."""
+        data = self._c._get(f"{self.BASE}/users/{user_id}/friends")
+        return [Friend.from_dict(f) for f in data.get("data", [])]
+
+    def get_friend_count(self, user_id: int) -> int:
+        """Get the number of friends a user has."""
+        data = self._c._get(f"{self.BASE}/users/{user_id}/friends/count")
+        return data.get("count", 0)
+
+    def get_followers(self, user_id: int, limit: int = 100,
+                      cursor: Optional[str] = None) -> Page:
+        """Get users who follow a given user."""
+        params = {"limit": limit, "sortOrder": "Asc"}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/users/{user_id}/followers", params=params)
+        return Page.from_dict(data, Friend)
+
+    def get_follower_count(self, user_id: int) -> int:
+        """Get the follower count for a user."""
+        data = self._c._get(f"{self.BASE}/users/{user_id}/followers/count")
+        return data.get("count", 0)
+
+    def get_followings(self, user_id: int, limit: int = 100,
+                       cursor: Optional[str] = None) -> Page:
+        """Get users that a user is following."""
+        params = {"limit": limit, "sortOrder": "Asc"}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/users/{user_id}/followings", params=params)
+        return Page.from_dict(data, Friend)
+
+    def get_following_count(self, user_id: int) -> int:
+        """Get how many users a user is following."""
+        data = self._c._get(f"{self.BASE}/users/{user_id}/followings/count")
+        return data.get("count", 0)
+
+    def get_friend_requests(self, limit: int = 20,
+                            cursor: Optional[str] = None) -> Page:
+        """Get pending friend requests. Requires auth."""
+        self._c.require_auth("get_friend_requests")
+        params = {"limit": limit}
+        if cursor: params["cursor"] = cursor
+        data = self._c._get(f"{self.BASE}/my/friends/requests", params=params)
+        return Page.from_dict(data, Friend)
+
+    def send_friend_request(self, user_id: int) -> None:
+        """Send a friend request. Requires auth."""
+        self._c.require_auth("send_friend_request")
+        self._c._post(f"{self.BASE}/users/{user_id}/request-friendship")
+
+    def unfriend(self, user_id: int) -> None:
+        """Unfriend a user. Requires auth."""
+        self._c.require_auth("unfriend")
+        self._c._post(f"{self.BASE}/users/{user_id}/unfriend")
+
+    def accept_friend_request(self, user_id: int) -> None:
+        """Accept a friend request. Requires auth."""
+        self._c.require_auth("accept_friend_request")
+        self._c._post(f"{self.BASE}/users/{user_id}/accept-friend-request")
+
+    def decline_friend_request(self, user_id: int) -> None:
+        """Decline a friend request. Requires auth."""
+        self._c.require_auth("decline_friend_request")
+        self._c._post(f"{self.BASE}/users/{user_id}/decline-friend-request")