Playerok APIplayerok.com ↗

"""
Playerok.com Gaming Marketplace API Client

Parse API integration for extracting product listings, game details, categories,
and featured items from playerok.com - a Russian gaming marketplace.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Dict, Any, List


class ParseClient:
    """Client for interacting with the Playerok.com Gaming Marketplace API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: API key for Parse. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "4688010c-bf13-44a2-bef6-4db5e643b286"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key not provided. Set PARSE_API_KEY environment variable or pass it as argument.")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name (e.g., 'list_items')
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to pass to the endpoint

        Returns:
            Response data as dictionary

        Raises:
            requests.RequestException: If the API request fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params, timeout=30)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params, timeout=30)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_games(self, query: Optional[str] = None, game_type: Optional[str] = None, limit: int = 24) -> Dict[str, Any]:
        """
        Search for games by name or list games by type.

        Args:
            query: Search query to filter games by name (e.g., 'Genshin')
            game_type: Filter by game type: GAME, MOBILE_GAME, or APPLICATION
            limit: Number of games to return (max 50)

        Returns:
            Dictionary containing games list and total count
        """
        params = {"limit": min(limit, 50)}
        if query:
            params["query"] = query
        if game_type:
            params["game_type"] = game_type

        return self._call("search_games", method="GET", **params)

    def list_categories(self, limit: int = 24) -> Dict[str, Any]:
        """
        List all marketplace categories.

        Args:
            limit: Number of categories to return (max 50)

        Returns:
            Dictionary containing categories list and total count
        """
        return self._call("list_categories", method="GET", limit=min(limit, 50))

    def list_items(
        self,
        game_id: Optional[str] = None,
        game_category_id: Optional[str] = None,
        game_slug: Optional[str] = None,
        category_slug: Optional[str] = None,
        limit: int = 24,
        cursor: Optional[str] = None,
        sort_field: Optional[str] = None,
        sort_direction: str = "ASC"
    ) -> Dict[str, Any]:
        """
        List products/items with filtering by game, category, sorting, and pagination.

        Args:
            game_id: Game UUID to filter by
            game_category_id: Game category UUID to filter by
            game_slug: Game slug to filter by (e.g., 'genshin-impact')
            category_slug: Category slug to filter by (e.g., 'coins')
            limit: Number of items per page (max 50)
            cursor: Pagination cursor from page_info.end_cursor
            sort_field: Sort field (e.g., 'price', 'createdAt')
            sort_direction: Sort direction: ASC or DESC

        Returns:
            Dictionary containing products list, total count, and pagination info
        """
        params = {"limit": min(limit, 50), "sort_direction": sort_direction}

        if game_id:
            params["game_id"] = game_id
        if game_category_id:
            params["game_category_id"] = game_category_id
        if game_slug:
            params["game_slug"] = game_slug
        if category_slug:
            params["category_slug"] = category_slug
        if cursor:
            params["cursor"] = cursor
        if sort_field:
            params["sort_field"] = sort_field

        return self._call("list_items", method="GET", **params)

    def get_item(self, slug: str) -> Dict[str, Any]:
        """
        Get detailed information about a single product by its slug.

        Args:
            slug: Product slug

        Returns:
            Dictionary containing detailed product information
        """
        return self._call("get_item", method="GET", slug=slug)

    def get_top_items(self, limit: int = 16) -> Dict[str, Any]:
        """
        Get featured/top products from the marketplace homepage.

        Args:
            limit: Number of top items to return (max 50)

        Returns:
            Dictionary containing top products list and total count
        """
        return self._call("get_top_items", method="GET", limit=min(limit, 50))


def main():
    """Practical workflow example: Search for Genshin Impact items and display details."""

    # Initialize client
    client = ParseClient()

    print("=" * 60)
    print("PLAYEROK GAMING MARKETPLACE API - PRACTICAL EXAMPLE")
    print("=" * 60)

    # Step 1: Search for Genshin Impact game
    print("\n1. Searching for 'Genshin Impact' game...")
    games_response = client.search_games(query="Genshin")
    games = games_response.get("games", [])

    if not games:
        print("No games found for 'Genshin'")
        return

    genshin = games[0]
    print(f"   Found: {genshin['name']} (ID: {genshin['id']})")
    print(f"   Game type: {genshin['type']}")
    print(f"   Categories available: {len(genshin.get('categories', []))}")

    # Step 2: List categories for reference
    print("\n2. Available marketplace categories:")
    categories_response = client.list_categories(limit=10)
    categories = categories_response.get("categories", [])
    for cat in categories[:5]:
        print(f"   - {cat['name']} ({cat['slug']})")

    # Step 3: List items for Genshin Impact, sorted by price
    print(f"\n3. Fetching Genshin Impact items (sorted by price, ascending)...")
    items_response = client.list_items(
        game_id=genshin['id'],
        limit=5,
        sort_field="price",
        sort_direction="ASC"
    )

    products = items_response.get("products", [])
    total_count = items_response.get("total_count", 0)
    page_info = items_response.get("page_info", {})

    print(f"   Total items in marketplace: {total_count}")
    print(f"   Showing: {len(products)} items")
    print(f"   Has next page: {page_info.get('has_next_page', False)}")

    # Step 4: Display item details and get full info for first item
    if products:
        print("\n4. Featured items from Genshin Impact:")
        first_item = products[0]

        for i, item in enumerate(products[:3], 1):
            seller = item.get("seller", {})
            price = item.get("price", "N/A")
            category = item.get("category", {})

            print(f"\n   Item {i}: {item['name']}")
            print(f"   Price: {price}₽ (Original: {item.get('raw_price', 'N/A')}₽)")
            print(f"   Seller: {seller.get('username')} (Rating: {seller.get('rating')}, Reviews: {seller.get('testimonial_count')})")
            print(f"   Category: {category.get('name')}")
            print(f"   Status: {item.get('status')}")
            print(f"   Priority: {item.get('priority')}")

        # Step 5: Get detailed information about the first item
        print(f"\n5. Getting detailed information for first item...")
        try:
            detailed_item = client.get_item(first_item['slug'])

            print(f"   Product ID: {detailed_item.get('id')}")
            print(f"   Full description preview: {detailed_item.get('description', 'N/A')[:100]}...")

            attributes = detailed_item.get("attributes", {})
            if attributes:
                print(f"   Attributes: {attributes}")

            obtaining_type = detailed_item.get("obtaining_type", {})
            if obtaining_type:
                print(f"   Delivery method: {obtaining_type.get('name')}")
                print(f"   Description: {obtaining_type.get('description')}")

            images = detailed_item.get("images", [])
            if images:
                print(f"   Number of images: {len(images)}")
                print(f"   First image URL: {images[0].get('url', 'N/A')[:50]}...")

        except Exception as e:
            print(f"   Error getting item details: {e}")

    # Step 6: Get top featured items from marketplace
    print("\n6. Fetching top featured items from marketplace...")
    top_response = client.get_top_items(limit=5)
    top_items = top_response.get("products", [])

    print(f"   Top items count: {len(top_items)}")
    if top_items:
        for i, item in enumerate(top_items[:3], 1):
            game = item.get("game", {})
            seller = item.get("seller", {})
            print(f"\n   Top {i}: {item['name']}")
            print(f"   Game: {game.get('name')}")
            print(f"   Price: {item.get('price')}₽")
            print(f"   Seller: {seller.get('username')} (Rating: {seller.get('rating')})")

    print("\n" + "=" * 60)
    print("Example workflow completed successfully!")
    print("=" * 60)


if __name__ == "__main__":
    main()