robase-utils 2.3.0__py3-none-any.whl

roboat_utils/client.py

@@ -0,0 +1,332 @@
+"""
+roboat_utils.client
+~~~~~~~~~~~~~~~~~~~~
+RoboatClient and ClientBuilder — main entry points.
+
+Bug fixes vs original:
+  - ClientBuilder had wrong attribute names (set_cookie stored to self._cookie
+    but method was named set_oauth_token)
+  - RoboatClient.__init__ referenced undefined `cookie` variable
+  - set_oauth_token set self._oauth_token = oauth_token BEFORE assigning param
+  - robux() method had dead code after raise NotImplementedError
+  - _handle_response 403 branch didn't return; fell through to raise
+  - _get/_post/_patch/_delete didn't pass url to raise_for_response for
+    accurate not-found subclass selection
+"""
+
+from __future__ import annotations
+
+import requests
+from typing import Optional
+
+from .exceptions import (
+    RoboatAPIError, RateLimitedError, NotAuthenticatedError, raise_for_response,
+)
+from .utils.cache     import TTLCache
+from .utils.ratelimit import TokenBucket
+
+
+class ClientBuilder:
+    """
+    Fluent builder for RoboatClient.
+
+    Example::
+
+        client = (
+            ClientBuilder()
+            .set_cookie("_|WARNING:...")
+            .set_timeout(15)
+            .set_cache_ttl(60)
+            .set_rate_limit(10)
+            .build()
+        )
+    """
+
+    def __init__(self) -> None:
+        self._cookie:     Optional[str]  = None
+        self._timeout:    int            = 10
+        self._proxies:    Optional[dict] = None
+        self._cache_ttl:  float          = 30.0
+        self._cache_size: int            = 512
+        self._rate_limit: float          = 10.0
+
+    def set_cookie(self, cookie: str) -> "ClientBuilder":
+        """Set the .ROBLOSECURITY cookie for authenticated requests."""
+        self._cookie = cookie
+        return self
+
+    # Keep old name for backwards compatibility
+    def set_oauth_token(self, token: str) -> "ClientBuilder":
+        """Alias for set_cookie (the original used this name incorrectly)."""
+        self._cookie = token
+        return self
+
+    def set_timeout(self, seconds: int) -> "ClientBuilder":
+        self._timeout = seconds
+        return self
+
+    def set_proxy(self, http: str, https: Optional[str] = None) -> "ClientBuilder":
+        self._proxies = {"http": http, "https": https or http}
+        return self
+
+    def set_cache_ttl(self, seconds: float) -> "ClientBuilder":
+        """Set how long API responses are cached. Pass 0 to disable."""
+        self._cache_ttl = max(0.0, seconds)
+        return self
+
+    def set_cache_size(self, max_entries: int) -> "ClientBuilder":
+        self._cache_size = max_entries
+        return self
+
+    def set_rate_limit(self, requests_per_second: float) -> "ClientBuilder":
+        self._rate_limit = requests_per_second
+        return self
+
+    def build(self) -> "RoboatClient":
+        return RoboatClient(
+            cookie=self._cookie,
+            timeout=self._timeout,
+            proxies=self._proxies,
+            cache_ttl=self._cache_ttl,
+            cache_size=self._cache_size,
+            rate_limit=self._rate_limit,
+        )
+
+
+class RoboatClient:
+    """
+    Full-featured Roblox API client.
+
+    Sub-APIs
+    --------
+    client.users        — User lookup, search, username history
+    client.games        — Games, visits, servers, votes, passes
+    client.catalog      — Avatar shop, items, resale, bundles
+    client.groups       — Groups, roles, members, wall, audit log
+    client.friends      — Friends, followers, followings, requests
+    client.thumbnails   — Thumbnail URLs for any resource type
+    client.badges       — Badges and award dates
+    client.economy      — Robux, transactions, resellers
+    client.presence     — Online / in-game status
+    client.avatar       — Avatar assets, colors, scales, outfits
+    client.trades       — Trade list, details, send, accept, decline
+    client.messages     — Private messages and chat
+    client.chat         — Chat conversations
+    client.inventory    — Inventory, collectibles, ownership checks
+    client.develop      — Universe/place management, datastores, stats
+    client.events       — Polling-based event system
+
+    Example::
+
+        client = RoboatClient(cookie="_|WARNING:...")
+        user = client.users.get_user(156)
+        print(user)
+    """
+
+    _BASE_HEADERS = {
+        "Accept":       "application/json",
+        "Content-Type": "application/json",
+        "User-Agent":   "roboat-utils/3.0 (https://github.com/Addi9000/roboat)",
+    }
+
+    def __init__(
+        self,
+        cookie:     Optional[str]  = None,
+        timeout:    int            = 10,
+        proxies:    Optional[dict] = None,
+        cache_ttl:  float          = 30.0,
+        cache_size: int            = 512,
+        rate_limit: float          = 10.0,
+    ) -> None:
+        self._cookie:      Optional[str] = None
+        self._csrf_token:  Optional[str] = None
+        self._timeout = timeout
+        self._cache   = TTLCache(default_ttl=cache_ttl, max_size=cache_size)
+        self._bucket  = TokenBucket(rate=rate_limit, capacity=rate_limit * 2)
+
+        self._session = requests.Session()
+        self._session.headers.update(self._BASE_HEADERS)
+        if proxies:
+            self._session.proxies.update(proxies)
+
+        # Attach sub-APIs (lazy imports avoid circular deps)
+        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
+        from .economy    import EconomyAPI
+        from .presence   import PresenceAPI
+        from .avatar     import AvatarAPI
+        from .trades     import TradesAPI
+        from .messages   import MessagesAPI, ChatAPI
+        from .inventory  import InventoryAPI
+        from .develop    import DevelopAPI
+        from .events     import EventPoller
+
+        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)
+        self.economy    = EconomyAPI(self)
+        self.presence   = PresenceAPI(self)
+        self.avatar     = AvatarAPI(self)
+        self.trades     = TradesAPI(self)
+        self.messages   = MessagesAPI(self)
+        self.chat       = ChatAPI(self)
+        self.inventory  = InventoryAPI(self)
+        self.develop    = DevelopAPI(self)
+        self.events     = EventPoller(self)
+
+        if cookie:
+            self.set_cookie(cookie)
+
+    # ── Auth ──────────────────────────────────────────────────────── #
+
+    def set_cookie(self, cookie: str) -> None:
+        """Set (or replace) the .ROBLOSECURITY cookie and refresh CSRF."""
+        self._cookie = cookie
+        self._session.cookies.set(".ROBLOSECURITY", cookie, domain=".roblox.com")
+        self._refresh_csrf()
+
+    # Backwards-compat alias used by original codebase
+    def set_oauth_token(self, token: str) -> None:
+        """Alias for set_cookie."""
+        self.set_cookie(token)
+
+    def _refresh_csrf(self) -> None:
+        """Silently refresh the X-CSRF-TOKEN from the logout endpoint."""
+        try:
+            r = self._session.post(
+                "https://auth.roblox.com/v2/logout",
+                timeout=self._timeout,
+            )
+            token = r.headers.get("x-csrf-token")
+            if token:
+                self._csrf_token = token
+                self._session.headers["x-csrf-token"] = token
+        except Exception:
+            pass
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._cookie is not None
+
+    def require_auth(self, method: str = "") -> None:
+        """Raise NotAuthenticatedError if no cookie is set."""
+        if not self.is_authenticated:
+            raise NotAuthenticatedError(method)
+
+    # ── HTTP helpers ─────────────────────────────────────────────── #
+
+    def _handle_response(self, resp: requests.Response) -> dict:
+        """
+        Parse a response, refreshing CSRF on 403 (Roblox-specific pattern)
+        and raising an appropriate exception on any other error.
+        """
+        # Roblox returns 403 with a new CSRF token when ours is stale.
+        # We DON'T want to raise here — the caller re-tries with the new token.
+        if resp.status_code == 403:
+            token = resp.headers.get("x-csrf-token")
+            if token:
+                self._csrf_token = token
+                self._session.headers["x-csrf-token"] = token
+                # Only re-raise if there's no token (genuine forbidden)
+                if not token:
+                    raise_for_response(403, {}, url=resp.url)
+                return {}  # signal caller to retry
+
+        if not resp.ok:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {}
+            raise_for_response(resp.status_code, body, url=str(resp.url))
+
+        try:
+            return resp.json()
+        except Exception:
+            return {}
+
+    def _get(self, url: str, **kwargs) -> dict:
+        self._bucket.consume()
+        kwargs.setdefault("timeout", self._timeout)
+        resp = self._session.get(url, **kwargs)
+        return self._handle_response(resp)
+
+    def _post(self, url: str, **kwargs) -> dict:
+        self._bucket.consume()
+        kwargs.setdefault("timeout", self._timeout)
+        resp = self._session.post(url, **kwargs)
+        result = self._handle_response(resp)
+        # Empty dict signals a stale CSRF — retry once
+        if result == {} and resp.status_code == 403:
+            resp = self._session.post(url, **kwargs)
+            return self._handle_response(resp)
+        return result
+
+    def _patch(self, url: str, **kwargs) -> dict:
+        self._bucket.consume()
+        kwargs.setdefault("timeout", self._timeout)
+        resp = self._session.patch(url, **kwargs)
+        result = self._handle_response(resp)
+        if result == {} and resp.status_code == 403:
+            resp = self._session.patch(url, **kwargs)
+            return self._handle_response(resp)
+        return result
+
+    def _delete(self, url: str, **kwargs) -> dict:
+        self._bucket.consume()
+        kwargs.setdefault("timeout", self._timeout)
+        resp = self._session.delete(url, **kwargs)
+        result = self._handle_response(resp)
+        if result == {} and resp.status_code == 403:
+            resp = self._session.delete(url, **kwargs)
+            return self._handle_response(resp)
+        return result
+
+    # ── Convenience shortcuts ─────────────────────────────────────── #
+
+    def user_id(self) -> int:
+        """Get the authenticated user's ID."""
+        self.require_auth("user_id")
+        return self.users.get_authenticated_user()["id"]
+
+    def username(self) -> str:
+        """Get the authenticated user's username."""
+        self.require_auth("username")
+        return self.users.get_authenticated_user()["name"]
+
+    def display_name(self) -> str:
+        """Get the authenticated user's display name."""
+        self.require_auth("display_name")
+        return self.users.get_authenticated_user()["displayName"]
+
+    def robux(self) -> int:
+        """Get the authenticated user's Robux balance."""
+        self.require_auth("robux")
+        uid = self.user_id()
+        return self.economy.get_robux_balance(uid).robux
+
+    def total_rap(self) -> int:
+        """Get total RAP of the authenticated user's limiteds."""
+        self.require_auth("total_rap")
+        return self.inventory.get_total_rap(self.user_id())
+
+    def invalidate_cache(self) -> None:
+        """Clear the entire response cache."""
+        self._cache.clear()
+
+    def cache_stats(self) -> dict:
+        """Return cache utilisation stats."""
+        return self._cache.stats()
+
+    def __repr__(self) -> str:
+        auth  = "authenticated" if self.is_authenticated else "unauthenticated"
+        cache = self._cache.stats()
+        return f"<RoboatClient [{auth}] cache={cache['alive']}/{cache['max_size']}>"

roboat_utils/database.py

@@ -0,0 +1,258 @@
+"""
+roboat.database
+~~~~~~~~~~~~~~~~~~
+Local SQLite-backed session database.
+Stores user data, game data, and session history locally.
+"""
+
+from __future__ import annotations
+import sqlite3
+import json
+import os
+from datetime import datetime
+from typing import Optional, Any
+from roboat_utils.exceptions import DatabaseError
+
+
+class SessionDatabase:
+    """
+    Lightweight local SQLite database for persisting roboat session data.
+
+    Usage::
+
+        db = SessionDatabase.create("mysession")   # new DB
+        db = SessionDatabase.load("mysession")     # existing DB
+
+    Tables:
+        users    — cached user records
+        games    — cached game records
+        sessions — session metadata / notes
+        log      — command history
+    """
+
+    _EXTENSION = ".robloxdb"
+
+    def __init__(self, path: str):
+        self.path = path
+        self.name = os.path.splitext(os.path.basename(path))[0]
+        self._conn: Optional[sqlite3.Connection] = None
+        self._connect()
+        self._init_schema()
+
+    # ------------------------------------------------------------------ #
+    #  Factory methods                                                     #
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def create(cls, name: str, directory: str = ".") -> "SessionDatabase":
+        """Create a new database. Raises if it already exists."""
+        path = cls._resolve_path(name, directory)
+        if os.path.exists(path):
+            raise DatabaseError(f"Database '{name}' already exists at {path}. Use load() instead.")
+        return cls(path)
+
+    @classmethod
+    def load(cls, name: str, directory: str = ".") -> "SessionDatabase":
+        """Load an existing database. Raises if not found."""
+        path = cls._resolve_path(name, directory)
+        if not os.path.exists(path):
+            raise DatabaseError(f"Database '{name}' not found at {path}. Use create() instead.")
+        return cls(path)
+
+    @classmethod
+    def load_or_create(cls, name: str, directory: str = ".") -> "SessionDatabase":
+        """Load if exists, otherwise create."""
+        path = cls._resolve_path(name, directory)
+        return cls(path)
+
+    @classmethod
+    def _resolve_path(cls, name: str, directory: str) -> str:
+        if not name.endswith(cls._EXTENSION):
+            name = name + cls._EXTENSION
+        return os.path.join(directory, name)
+
+    @classmethod
+    def list_databases(cls, directory: str = ".") -> list:
+        """List all .robloxdb files in a directory."""
+        try:
+            return [
+                f[:-len(cls._EXTENSION)]
+                for f in os.listdir(directory)
+                if f.endswith(cls._EXTENSION)
+            ]
+        except FileNotFoundError:
+            return []
+
+    # ------------------------------------------------------------------ #
+    #  Connection                                                          #
+    # ------------------------------------------------------------------ #
+
+    def _connect(self):
+        self._conn = sqlite3.connect(self.path)
+        self._conn.row_factory = sqlite3.Row
+
+    def close(self):
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def _init_schema(self):
+        self._conn.executescript("""
+            CREATE TABLE IF NOT EXISTS users (
+                user_id     INTEGER PRIMARY KEY,
+                username    TEXT,
+                display_name TEXT,
+                description TEXT,
+                is_banned   INTEGER DEFAULT 0,
+                verified    INTEGER DEFAULT 0,
+                cached_at   TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS games (
+                universe_id  INTEGER PRIMARY KEY,
+                place_id     INTEGER,
+                name         TEXT,
+                description  TEXT,
+                creator_name TEXT,
+                visits       INTEGER DEFAULT 0,
+                playing      INTEGER DEFAULT 0,
+                max_players  INTEGER DEFAULT 0,
+                genre        TEXT,
+                cached_at    TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS sessions (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                key         TEXT UNIQUE,
+                value       TEXT,
+                updated_at  TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS log (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                command     TEXT,
+                result      TEXT,
+                ran_at      TEXT
+            );
+        """)
+        self._conn.commit()
+
+    # ------------------------------------------------------------------ #
+    #  Users                                                               #
+    # ------------------------------------------------------------------ #
+
+    def save_user(self, user) -> None:
+        """Cache a User model to the database."""
+        self._conn.execute("""
+            INSERT OR REPLACE INTO users
+              (user_id, username, display_name, description, is_banned, verified, cached_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (
+            user.id, user.name, user.display_name, user.description,
+            int(user.is_banned), int(user.has_verified_badge),
+            datetime.utcnow().isoformat(),
+        ))
+        self._conn.commit()
+
+    def get_user(self, user_id: int) -> Optional[dict]:
+        """Retrieve a cached user by ID."""
+        row = self._conn.execute(
+            "SELECT * FROM users WHERE user_id = ?", (user_id,)
+        ).fetchone()
+        return dict(row) if row else None
+
+    def get_all_users(self) -> list:
+        rows = self._conn.execute("SELECT * FROM users ORDER BY cached_at DESC").fetchall()
+        return [dict(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    #  Games                                                               #
+    # ------------------------------------------------------------------ #
+
+    def save_game(self, game) -> None:
+        """Cache a Game model to the database."""
+        self._conn.execute("""
+            INSERT OR REPLACE INTO games
+              (universe_id, place_id, name, description, creator_name,
+               visits, playing, max_players, genre, cached_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            game.id, game.root_place_id, game.name, game.description,
+            game.creator_name, game.visits, game.playing, game.max_players,
+            game.genre, datetime.utcnow().isoformat(),
+        ))
+        self._conn.commit()
+
+    def get_game(self, universe_id: int) -> Optional[dict]:
+        row = self._conn.execute(
+            "SELECT * FROM games WHERE universe_id = ?", (universe_id,)
+        ).fetchone()
+        return dict(row) if row else None
+
+    def get_all_games(self) -> list:
+        rows = self._conn.execute("SELECT * FROM games ORDER BY visits DESC").fetchall()
+        return [dict(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    #  Session key-value store                                            #
+    # ------------------------------------------------------------------ #
+
+    def set(self, key: str, value: Any) -> None:
+        """Store any JSON-serialisable value under a key."""
+        self._conn.execute("""
+            INSERT OR REPLACE INTO sessions (key, value, updated_at)
+            VALUES (?, ?, ?)
+        """, (key, json.dumps(value), datetime.utcnow().isoformat()))
+        self._conn.commit()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a stored value by key."""
+        row = self._conn.execute(
+            "SELECT value FROM sessions WHERE key = ?", (key,)
+        ).fetchone()
+        if row:
+            try:
+                return json.loads(row["value"])
+            except Exception:
+                return row["value"]
+        return default
+
+    def delete(self, key: str) -> None:
+        self._conn.execute("DELETE FROM sessions WHERE key = ?", (key,))
+        self._conn.commit()
+
+    def keys(self) -> list:
+        rows = self._conn.execute("SELECT key FROM sessions").fetchall()
+        return [r["key"] for r in rows]
+
+    # ------------------------------------------------------------------ #
+    #  Log                                                                 #
+    # ------------------------------------------------------------------ #
+
+    def log_command(self, command: str, result: str = "") -> None:
+        """Log a terminal command and its result."""
+        self._conn.execute(
+            "INSERT INTO log (command, result, ran_at) VALUES (?, ?, ?)",
+            (command, result[:500], datetime.utcnow().isoformat()),
+        )
+        self._conn.commit()
+
+    def get_log(self, limit: int = 50) -> list:
+        rows = self._conn.execute(
+            "SELECT * FROM log ORDER BY ran_at DESC LIMIT ?", (limit,)
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    #  Stats                                                               #
+    # ------------------------------------------------------------------ #
+
+    def stats(self) -> dict:
+        users = self._conn.execute("SELECT COUNT(*) FROM users").fetchone()[0]
+        games = self._conn.execute("SELECT COUNT(*) FROM games").fetchone()[0]
+        logs  = self._conn.execute("SELECT COUNT(*) FROM log").fetchone()[0]
+        keys  = self._conn.execute("SELECT COUNT(*) FROM sessions").fetchone()[0]
+        return {"users": users, "games": games, "session_keys": keys, "log_entries": logs}
+
+    def __repr__(self) -> str:
+        return f"<SessionDatabase '{self.name}' at {self.path}>"