stakeapi-codestats 0.2.0__py3-none-any.whl

stakeapi/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for StakeAPI."""
+
+
+class StakeAPIError(Exception):
+    """Base exception for StakeAPI errors."""
+
+    pass
+
+
+class AuthenticationError(StakeAPIError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class RateLimitError(StakeAPIError):
+    """Raised when rate limit is exceeded."""
+
+    pass
+
+
+class ValidationError(StakeAPIError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class NetworkError(StakeAPIError):
+    """Raised when network requests fail."""
+
+    pass
+
+
+class GameNotFoundError(StakeAPIError):
+    """Raised when a requested game is not found."""
+
+    pass
+
+
+class InsufficientFundsError(StakeAPIError):
+    """Raised when user has insufficient funds for an operation."""
+
+    pass

stakeapi/models.py

@@ -0,0 +1,285 @@
+"""Data models for StakeAPI.
+
+Models reflect the actual GraphQL API response shapes as verified
+against stake.com and stake.us on 2025-05-09/10.
+
+Pydantic v2 model_config handles camelCase (from API) <-> snake_case (Python)
+conversion via alias_generator.
+"""
+
+from decimal import Decimal
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel as _BaseModel
+from pydantic import ConfigDict, Field
+
+
+def _to_camel(name: str) -> str:
+    first, *rest = name.split("_")
+    return first + "".join(r.capitalize() for r in rest)
+
+
+class StakeModel(_BaseModel):
+    """Base model with camelCase alias support."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=_to_camel,
+    )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StakeModel":
+        return cls(**data)
+
+
+class BalanceEntry(StakeModel):
+    """Available or vault balance for a single currency."""
+
+    amount: Decimal = Decimal("0")
+    currency: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BalanceEntry":
+        return cls(**data)
+
+
+class User(StakeModel):
+    """User model matching the real GraphQL user shape."""
+
+    id: str = ""
+    name: str = ""
+    email: Optional[str] = None
+    has_email_verified: bool = False
+    is_muted: bool = False
+    is_rainproof: bool = False
+    is_banned: bool = False
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "User":
+        return cls(**data)
+
+
+class SessionInfo(StakeModel):
+    """Session entry from user.sessionList."""
+
+    id: str = ""
+    session_name: Optional[str] = None
+    ip: Optional[str] = None
+    active: bool = False
+    country: Optional[str] = None
+    city: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SessionInfo":
+        return cls(**data)
+
+
+class ApiKeyInfo(StakeModel):
+    """API key entry from user.apiKeys."""
+
+    id: str = ""
+    ip: Optional[str] = None
+    active: bool = False
+    session_name: Optional[str] = None
+    type: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ApiKeyInfo":
+        return cls(**data)
+
+
+class StatisticEntry(StakeModel):
+    """Per-currency wagering statistic from user.statistic."""
+
+    id: str = ""
+    bet_amount: Decimal = Decimal("0")
+    profit: Decimal = Decimal("0")
+    amount: Decimal = Decimal("0")
+    currency: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StatisticEntry":
+        return cls(**data)
+
+
+class SeedPair(StakeModel):
+    """Active client/server seed pair."""
+
+    client_seed: str = ""
+    server_seed_hash: str = ""
+    nonce: int = 0
+    next_seed_hash: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SeedPair":
+        return cls(**data)
+
+
+class FaucetInfo(StakeModel):
+    """Reload/faucet status."""
+
+    id: str = ""
+    active: bool = False
+    value: Decimal = Decimal("0")
+    claim_interval: Optional[int] = None
+    last_claim: Optional[str] = None
+    expire_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FaucetInfo":
+        return cls(**data)
+
+
+class TransactionEntry(StakeModel):
+    """Single transaction from user.transaction."""
+
+    id: str = ""
+    amount: Decimal = Decimal("0")
+    currency: str = ""
+    type: str = ""
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TransactionEntry":
+        return cls(**data)
+
+
+class BlackjackCard(StakeModel):
+    """Card in a blackjack hand."""
+
+    rank: str = ""
+    suit: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BlackjackCard":
+        return cls(**data)
+
+
+class BlackjackHand(StakeModel):
+    """Blackjack hand (player or dealer)."""
+
+    value: int = 0
+    actions: List[str] = Field(default_factory=list)
+    cards: List[BlackjackCard] = Field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BlackjackHand":
+        return cls(**data)
+
+
+class BlackjackBet(StakeModel):
+    """Active blackjack bet."""
+
+    id: str = ""
+    active: bool = False
+    nonce: int = 0
+    payout_multiplier: Decimal = Decimal("0")
+    amount_multiplier: Decimal = Decimal("0")
+    amount: Decimal = Decimal("0")
+    payout: Decimal = Decimal("0")
+    updated_at: Optional[str] = None
+    currency: str = ""
+    game: str = ""
+    player: Optional[BlackjackHand] = None
+    dealer: Optional[BlackjackHand] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BlackjackBet":
+        return cls(**data)
+
+
+class BonusCodeInfo(StakeModel):
+    """Bonus code availability info."""
+
+    availability_status: str = ""
+    bonus_value: Optional[Decimal] = None
+    crypto_multiplier: Optional[Decimal] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BonusCodeInfo":
+        return cls(**data)
+
+
+class KuratorGame(StakeModel):
+    """Game entry in a kurator collection/group."""
+
+    id: str = ""
+    name: str = ""
+    slug: str = ""
+    provider: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KuratorGame":
+        return cls(**data)
+
+
+class KuratorCollection(StakeModel):
+    """Kurator game collection."""
+
+    id: str = ""
+    name: str = ""
+    slug: str = ""
+    games: List[KuratorGame] = Field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KuratorCollection":
+        return cls(**data)
+
+
+class CurrencyInfo(StakeModel):
+    """Currency configuration entry."""
+
+    name: str = ""
+    rates: List[Dict[str, Any]] = Field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CurrencyInfo":
+        return cls(**data)
+
+
+class SportItem(StakeModel):
+    """Sport menu entry."""
+
+    id: str = ""
+    name: str = ""
+    slug: str = ""
+    icon: Optional[str] = None
+    active: bool = False
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SportItem":
+        return cls(**data)
+
+
+class RaceInfo(StakeModel):
+    """Active race entry."""
+
+    id: str = ""
+    name: str = ""
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    prize: Optional[Decimal] = None
+    currency: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "RaceInfo":
+        return cls(**data)
+
+
+class NotificationEntry(StakeModel):
+    """Notification entry."""
+
+    id: str = ""
+    type: Optional[str] = None
+    message: Optional[str] = None
+    read: bool = False
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "NotificationEntry":
+        return cls(**data)

stakeapi/utils.py

@@ -0,0 +1,141 @@
+"""Utility functions for StakeAPI."""
+
+import re
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, Optional
+
+
+def validate_api_key(api_key: str) -> bool:
+    """
+    Validate API key format.
+
+    Args:
+        api_key: The API key to validate
+
+    Returns:
+        True if valid format
+    """
+    if not api_key or not isinstance(api_key, str):
+        return False
+
+    # Basic format validation (adjust based on actual format)
+    pattern = r"^[a-zA-Z0-9]{32,64}$"
+    return bool(re.match(pattern, api_key))
+
+
+def safe_decimal(value: Any) -> Optional[Decimal]:
+    """
+    Safely convert value to Decimal.
+
+    Args:
+        value: Value to convert
+
+    Returns:
+        Decimal value or None if conversion fails
+    """
+    if value is None:
+        return None
+
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, ValueError, TypeError):
+        return None
+
+
+def parse_datetime(date_string: str) -> Optional[datetime]:
+    """
+    Parse datetime string to datetime object.
+
+    Args:
+        date_string: ISO format datetime string
+
+    Returns:
+        Datetime object or None if parsing fails
+    """
+    if not date_string:
+        return None
+
+    try:
+        # Try parsing ISO format with timezone
+        return datetime.fromisoformat(date_string.replace("Z", "+00:00"))
+    except ValueError:
+        try:
+            # Try parsing without timezone
+            dt = datetime.fromisoformat(date_string)
+            return dt.replace(tzinfo=timezone.utc)
+        except ValueError:
+            return None
+
+
+def format_currency(amount: Decimal, currency: str = "USD") -> str:
+    """
+    Format currency amount for display.
+
+    Args:
+        amount: Amount to format
+        currency: Currency code
+
+    Returns:
+        Formatted currency string
+    """
+    if currency.upper() == "USD":
+        return f"${amount:.2f}"
+    elif currency.upper() == "EUR":
+        return f"€{amount:.2f}"
+    elif currency.upper() == "GBP":
+        return f"£{amount:.2f}"
+    else:
+        return f"{amount:.2f} {currency.upper()}"
+
+
+def calculate_win_rate(wins: int, total_bets: int) -> float:
+    """
+    Calculate win rate percentage.
+
+    Args:
+        wins: Number of wins
+        total_bets: Total number of bets
+
+    Returns:
+        Win rate as percentage (0-100)
+    """
+    if total_bets == 0:
+        return 0.0
+
+    return (wins / total_bets) * 100
+
+
+def validate_bet_amount(amount: Decimal, min_bet: Decimal, max_bet: Decimal) -> bool:
+    """
+    Validate bet amount is within limits.
+
+    Args:
+        amount: Bet amount
+        min_bet: Minimum bet amount
+        max_bet: Maximum bet amount
+
+    Returns:
+        True if amount is valid
+    """
+    return min_bet <= amount <= max_bet
+
+
+def sanitize_game_name(name: str) -> str:
+    """
+    Sanitize game name for safe usage.
+
+    Args:
+        name: Game name to sanitize
+
+    Returns:
+        Sanitized game name
+    """
+    if not name:
+        return ""
+
+    # Remove special characters and normalize spaces
+    sanitized = re.sub(r"[^\w\s-]", "", name)
+    sanitized = re.sub(r"\s+", " ", sanitized).strip()
+
+    return sanitized

stakeapi_codestats-0.2.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: stakeapi-codestats
+Version: 0.2.0
+Summary: Unofficial async Python wrapper for the stake.com / stake.us GraphQL API — CodeStats.gg edition
+Author: brokechubb
+License: MIT
+Project-URL: Homepage, https://codestats.gg
+Project-URL: Documentation, https://brokechubb.github.io/StakeAPI/
+Project-URL: Repository, https://github.com/brokechubb/StakeAPI
+Project-URL: Bug Tracker, https://github.com/brokechubb/StakeAPI/issues
+Keywords: stake,gambling,api,casino,betting,codestats,graphql,stake.us
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: websockets>=10.0
+Requires-Dist: cryptography>=3.4.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.910; extra == "dev"
+Requires-Dist: pre-commit>=2.15.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Requires-Dist: myst-parser>=0.15.0; extra == "docs"
+Dynamic: license-file
+
+# StakeAPI
+
+### UPDATED MAY 2026
+
+An unofficial async Python wrapper for the stake.com / stake.us GraphQL API.
+
+## Disclaimer
+
+This is an unofficial wrapper, not affiliated with or endorsed by Stake.com or Stake.us. Use at your own risk and ensure compliance with all applicable laws and the platform's terms of service.
+
+## Features
+
+- Async/await with `aiohttp`
+- All GraphQL operations verified against live stake.com and stake.us APIs
+- Pydantic v2 models with camelCase alias support
+- Cloudflare bypass via `cf_clearance` cookie + matching User-Agent
+- stake.us works with access token only — no Cloudflare cookie required
+
+## Installation
+
+```bash
+pip install stakeapi-codestats
+```
+
+## Quick Start
+
+```python
+import asyncio
+from stakeapi import StakeAPI
+
+async def main():
+    # stake.us — access token only
+    async with StakeAPI(
+        access_token="your_token",
+        base_url="https://stake.us",
+    ) as client:
+        balance = await client.get_user_balance()
+        print(balance)
+
+asyncio.run(main())
+```
+
+### stake.com (requires Cloudflare clearance)
+
+stake.com blocks requests without a valid `cf_clearance` cookie. Get it from your browser's DevTools (Application → Cookies → `cf_clearance`) or extract it with Playwright:
+
+```python
+async with StakeAPI(
+    access_token="your_token",
+    cf_clearance="your_cf_clearance_cookie",
+    user_agent="Mozilla/5.0 ... Chrome/147.0.0.0 ...",  # must match cookie
+    base_url="https://stake.com",
+) as client:
+    balance = await client.get_user_balance()
+```
+
+## Getting Your Access Token
+
+1. Log in to stake.com in your browser
+2. Open DevTools (F12) → Network tab
+3. Make any action that triggers a request to `/_api/graphql`
+4. Find the `x-access-token` request header — that's your token
+
+## API Methods
+
+### User
+
+| Method                                      | Description                             |
+| ------------------------------------------- | --------------------------------------- |
+| `get_user_balance()`                        | Available + vault balances per currency |
+| `get_user_profile()`                        | Name, email, verification status        |
+| `get_user_meta(name=None)`                  | Lightweight user info with balances     |
+| `get_user_meta_extended(name, signup_code)` | Extended info including self-exclude    |
+| `get_user_account_info()`                   | Name, email, createdAt                  |
+| `get_user_kyc_status()`                     | KYC status (stake.com only)             |
+| `get_user_sessions()`                       | Active sessions with IP and location    |
+| `get_user_api_keys()`                       | API key list                            |
+| `get_user_statistic()`                      | Per-currency wagering stats             |
+| `get_user_seed_pair()`                      | Provably fair client/server seeds       |
+| `is_user_tfa_enabled()`                     | 2FA status                              |
+| `get_user_preferences()`                    | User preferences object                 |
+| `get_user_recent_games(limit)`              | Recently played games                   |
+
+### VIP / Reload / Faucet
+
+| Method                  | Description                           |
+| ----------------------- | ------------------------------------- |
+| `get_vip_meta()`        | Balances + reload status combined     |
+| `get_faucet()`          | Reload/faucet status                  |
+| `get_active_rakeback()` | Rakeback info (permission-restricted) |
+| `get_tip_list(limit)`   | User tip history                      |
+
+### Currency / Config
+
+| Method                                     | Description                                       |
+| ------------------------------------------ | ------------------------------------------------- |
+| `get_currency_configuration(is_acp)`       | Currency rates; `is_acp=True` for stake.us        |
+| `get_conversion_rates(display_currencies)` | Fiat conversion rates (lowercase enum: `["usd"]`) |
+
+### Bonuses / Promos
+
+| Method                                | Description             |
+| ------------------------------------- | ----------------------- |
+| `check_bonus_code(code, coupon_type)` | Check code availability |
+| `get_racing_list()`                   | Race/campaign list      |
+| `get_campaign_balances()`             | User campaign balances  |
+
+### Transactions / History
+
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `get_transactions(offset, limit, types)` | Transaction history with optional type filter      |
+| `get_deposits(offset, limit)`            | Deposit history                                    |
+| `get_withdrawals(offset, limit)`         | Withdrawal history                                 |
+| `get_my_bets(limit)`                     | Chat list (direct bet history unavailable via API) |
+
+### Casino / Games
+
+| Method                                    | Description                                   |
+| ----------------------------------------- | --------------------------------------------- |
+| `get_blackjack_active_bet()`              | Active BJ bet or null                         |
+| `get_kurator_collection(collection_type)` | Game collection by enum type                  |
+| `get_kurator_group(slug)`                 | Game group by slug (e.g. `"stake-originals"`) |
+
+### Sports (stake.com only)
+
+| Method                  | Description                            |
+| ----------------------- | -------------------------------------- |
+| `get_sport_list_menu()` | Sport list (region-locked on stake.us) |
+
+### Social / Misc
+
+| Method                             | Description                             |
+| ---------------------------------- | --------------------------------------- |
+| `get_active_races()`               | Active races                            |
+| `get_notifications(offset, limit)` | Notification list                       |
+| `get_public_chats()`               | Public chat entries                     |
+| `get_banned_countries()`           | Banned countries (CSV in `value` field) |
+| `get_player_count()`               | Player count by scope                   |
+| `get_feature_flags()`              | Feature flag list                       |
+
+### Mutations
+
+| Method                                              | Description                |
+| --------------------------------------------------- | -------------------------- |
+| `claim_bonus_code(code, currency, turnstile_token)` | Claim a bonus code         |
+| `claim_faucet(currency, turnstile_token)`           | Claim reload bonus         |
+| `claim_rakeback()`                                  | Claim rakeback             |
+| `create_vault_deposit(currency, amount)`            | Deposit to vault           |
+| `rotate_seed_pair(seed)`                            | Rotate provably fair seeds |
+| `blackjack_bet(amount, currency, identifier)`       | Place BJ bet               |
+| `blackjack_next(action, identifier)`                | Hit/stand/double           |
+
+> **Note:** `claim_bonus_code` and `claim_faucet` require a Cloudflare Turnstile token (sitekey `0x4AAAAAAAGD4gMGOTFnvupz`), which must be generated in a browser context.
+
+## Custom GraphQL Queries
+
+```python
+async with StakeAPI(access_token="token", base_url="https://stake.us") as client:
+    data = await client._graphql_request(
+        query="""
+        query UserSeedPair {
+          user {
+            id
+            activeClientSeed { seed }
+            activeServerSeed { seedHash nonce }
+          }
+        }
+        """,
+        operation_name="UserSeedPair",
+    )
+    print(data)
+```
+
+## Development
+
+```bash
+make install-dev   # install with dev deps
+make format        # black + isort
+make check         # lint + typecheck + tests
+```
+
+## License
+
+MIT