JetPunk APIjetpunk.com ↗

"""
JetPunk Trivia API Parse Client

Search and discover trivia quizzes from JetPunk by category or tag, then access 
detailed quiz questions and answers to test your knowledge or build custom trivia experiences.

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

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


class ParseClient:
    """Client for interacting with the JetPunk Trivia Parse API."""

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

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "8393ef45-4706-4d61-9693-127af45c4246"
        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.")

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

        Args:
            endpoint: The endpoint name (e.g., 'search_quizzes')
            method: HTTP method ('GET' or 'POST')
            **params: Query or body parameters

        Returns:
            Parsed JSON response
        """
        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)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_quizzes(
        self,
        query: str,
        page: int = 1
    ) -> Dict[str, Any]:
        """
        Search for quizzes by keyword on JetPunk.

        Args:
            query: Search keyword (e.g., 'Capitals', 'Countries')
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary containing quizzes list, page info, and has_next flag
        """
        return self._call(
            "search_quizzes",
            method="GET",
            query=query,
            page=page
        )

    def get_quizzes_by_tag(
        self,
        tag: str,
        page: int = 1
    ) -> Dict[str, Any]:
        """
        List quizzes in a specific category or tag.

        Args:
            tag: Tag or category name (e.g., 'geography', 'history', 'science')
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary containing quizzes list, tag, and pagination info
        """
        return self._call(
            "get_quizzes_by_tag",
            method="GET",
            tag=tag,
            page=page
        )

    def get_quiz(self, path: str) -> Dict[str, Any]:
        """
        Get full details of a quiz, including title, description, categories, and all questions/answers.

        Args:
            path: The URL path of the quiz (e.g., '/quizzes/european-capitals-quiz')

        Returns:
            Dictionary containing quiz details, headers, and content (question/answer pairs)
        """
        return self._call(
            "get_quiz",
            method="GET",
            path=path
        )


def format_takes(takes_str: str) -> str:
    """Format takes count with commas for readability."""
    try:
        return f"{int(takes_str):,}"
    except (ValueError, TypeError):
        return takes_str


def print_quiz_table(quiz: Dict[str, Any], max_rows: int = 5) -> None:
    """Print quiz content in a formatted table."""
    headers = quiz.get('headers', [])
    content = quiz.get('content', [])

    if not headers or not content:
        print("   No content available")
        return

    # Calculate column widths
    col_widths = {header: len(header) for header in headers}
    for row in content[:max_rows]:
        for header in headers:
            col_widths[header] = max(col_widths[header], len(str(row.get(header, ''))))

    # Print header
    header_line = " | ".join(f"{h:<{col_widths[h]}}" for h in headers)
    print(f"   {header_line}")
    print(f"   {'-' * len(header_line)}")

    # Print rows
    for row in content[:max_rows]:
        row_line = " | ".join(f"{str(row.get(h, '')):<{col_widths[h]}}" for h in headers)
        print(f"   {row_line}")

    if len(content) > max_rows:
        print(f"   ... and {len(content) - max_rows} more")


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()

    print("🧠 JetPunk Trivia API - Practical Workflow\n")
    print("=" * 70)

    # Step 1: Search for quizzes about capitals
    print("\n📍 Step 1: Searching for 'capitals' quizzes...")
    search_results = client.search_quizzes(query="capitals", page=1)
    
    quizzes_list = search_results.get('quizzes', [])
    print(f"   ✓ Found {len(quizzes_list)} quizzes")
    print(f"   ✓ Has next page: {search_results.get('has_next', False)}")
    print(f"   ✓ Query: '{search_results.get('query')}'")

    # Step 2: Get top quiz from search results
    if quizzes_list:
        top_quiz_info = quizzes_list[0]
        print(f"\n📍 Step 2: Fetching details for top search result...")
        print(f"   Title: {top_quiz_info['title']}")
        print(f"   Takes: {format_takes(top_quiz_info['takes'])}")

        try:
            top_quiz = client.get_quiz(path=top_quiz_info['path'])
            print(f"   ✓ Loaded quiz ID: {top_quiz.get('id')}")
            print(f"   ✓ Questions: {len(top_quiz.get('content', []))}")
            print(f"   ✓ Categories: {', '.join(top_quiz.get('categories', []))}")

            print(f"\n   Quiz Description: {top_quiz.get('description', 'N/A')}")
            print(f"\n   Sample Q&A Data:")
            print_quiz_table(top_quiz, max_rows=4)

        except Exception as e:
            print(f"   ✗ Error loading quiz: {e}")

    # Step 3: Browse quizzes by geography tag
    print(f"\n\n📍 Step 3: Browsing 'geography' category...")
    geography_results = client.get_quizzes_by_tag(tag="geography", page=1)
    
    geo_quizzes = geography_results.get('quizzes', [])
    print(f"   ✓ Found {len(geo_quizzes)} geography quizzes")
    print(f"   ✓ Tag: {geography_results.get('tag')}")
    print(f"   ✓ Has next page: {geography_results.get('has_next', False)}")

    # Step 4: Fetch and display details for top geography quizzes
    print(f"\n📍 Step 4: Loading details for top 2 geography quizzes...")
    for idx, geo_quiz_info in enumerate(geo_quizzes[:2], 1):
        print(f"\n   [{idx}] {geo_quiz_info['title']}")
        print(f"       Takes: {format_takes(geo_quiz_info['takes'])}")

        try:
            geo_quiz = client.get_quiz(path=geo_quiz_info['path'])
            print(f"       ✓ Quiz ID: {geo_quiz.get('id')}")
            print(f"       ✓ Total questions: {len(geo_quiz.get('content', []))}")
            print(f"       ✓ Categories: {', '.join(geo_quiz.get('categories', []))}")

            print(f"\n       Sample Content:")
            print_quiz_table(geo_quiz, max_rows=3)

        except Exception as e:
            print(f"       ✗ Error: {e}")

    print("\n" + "=" * 70)
    print("✅ Workflow completed successfully!")
    print("\nYou can now:")
    print("  • Search for any quiz topic using search_quizzes()")
    print("  • Browse categories using get_quizzes_by_tag()")
    print("  • Extract Q&A data using get_quiz(path)")