Royal Road APIroyalroad.com ↗

"""
Royal Road Fiction API Client
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Royal Road Fiction API via Parse."""

    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 = "195f0514-c4a2-4100-87c0-84b79b177517"
        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 api_key parameter."
            )

    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., 'search_fictions')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters for the request

        Returns:
            Parsed JSON response 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)
        else:  # POST
            response = requests.post(url, headers=headers, json=params)

        response.raise_for_status()
        return response.json()

    def search_fictions(
        self,
        title: Optional[str] = None,
        tags_add: Optional[str] = None,
        tags_remove: Optional[str] = None,
        genre: Optional[str] = None,
        order_by: Optional[str] = None,
        page: int = 1,
    ) -> Dict[str, Any]:
        """
        Search fictions by title, tags, and genre.

        Args:
            title: Title or keyword to search for
            tags_add: Tag to include in results (snake_case)
            tags_remove: Tag to exclude from results (snake_case)
            genre: Genre filter (e.g., 'fantasy', 'sci_fi', 'action')
            order_by: Sort order ('relevance', 'popularity', 'rating', 'name', 'pages', 'readers', 'date')
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary with 'results', 'page', 'total_pages', 'count'
        """
        params = {"page": str(page)}

        if title:
            params["title"] = title
        if tags_add:
            params["tags_add"] = tags_add
        if tags_remove:
            params["tags_remove"] = tags_remove
        if genre:
            params["genre"] = genre
        if order_by:
            params["order_by"] = order_by

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

    def get_fiction(self, fiction_id: str) -> Dict[str, Any]:
        """
        Get detailed information about a specific fiction.

        Args:
            fiction_id: Numeric fiction ID from Royal Road (e.g., '8300')

        Returns:
            Dictionary with fiction details including description, ratings, chapters, etc.
        """
        return self._call("get_fiction", method="GET", fiction_id=fiction_id)

    def list_fictions(
        self,
        category: str = "trending",
        page: int = 1,
    ) -> Dict[str, Any]:
        """
        List fictions from a specific category/ranking page.

        Args:
            category: Category to list. One of: 'best-rated', 'trending', 'active-popular',
                     'complete', 'weekly-popular', 'latest-updates', 'new', 'rising-stars', 'writathon'
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary with 'results', 'page', 'total_pages', 'count', 'category'
        """
        return self._call(
            "list_fictions", method="GET", category=category, page=str(page)
        )


def main():
    """Practical workflow example: Find LitRPG fictions and show details."""

    # Initialize the client
    client = ParseClient()

    print("=" * 70)
    print("Royal Road Fiction API - Practical Example")
    print("=" * 70)

    # Step 1: Search for LitRPG fictions with progression tag
    print("\n📚 Searching for LitRPG fictions with progression...")
    search_results = client.search_fictions(
        tags_add="litrpg",
        tags_add="progression" if False else None,  # Tags search example
        order_by="rating",
        page=1,
    )

    print(f"Found {search_results['count']} results (Page {search_results['page']} of {search_results['total_pages']})")

    if not search_results["results"]:
        print("No results found.")
        return

    # Step 2: Show top 3 results summary
    print("\n📖 Top Results:")
    top_fictions = search_results["results"][:3]

    for idx, fiction in enumerate(top_fictions, 1):
        print(f"\n{idx}. {fiction['title']}")
        print(f"   Rating: ⭐ {fiction['rating']}")
        print(f"   Followers: {fiction['followers']:,}")
        print(f"   Chapters: {fiction['chapters']}")
        print(f"   Views: {fiction['views']:,}")
        print(f"   ID: {fiction['fiction_id']}")

    # Step 3: Get detailed information for the top result
    if top_fictions:
        top_fiction_id = top_fictions[0]["fiction_id"]
        print(f"\n\n🔍 Fetching detailed info for '{top_fictions[0]['title']}'...")

        detailed_info = client.get_fiction(top_fiction_id)

        print(f"\n{'='*70}")
        print(f"Title: {detailed_info['title']}")
        print(f"Author: {detailed_info['author']}")
        print(f"Description: {detailed_info['description'][:200]}...")

        # Show ratings breakdown
        ratings = detailed_info["ratings"]
        print(f"\nRatings Breakdown:")
        print(f"  Overall: {ratings['overall_score']}")
        print(f"  Story: {ratings['story_score']}")
        print(f"  Style: {ratings['style_score']}")
        print(f"  Grammar: {ratings['grammar_score']}")
        print(f"  Character: {ratings['character_score']}")

        # Show content warnings
        if detailed_info["warnings"]:
            print(f"\n⚠️  Content Warnings:")
            for warning in detailed_info["warnings"]:
                print(f"  - {warning}")

        # Show tags
        print(f"\nTags: {', '.join(detailed_info['tags'])}")

        # Show recent chapters
        print(f"\nRecent Chapters ({len(detailed_info['chapters'])} total):")
        for chapter in detailed_info["chapters"][:3]:
            print(f"  - {chapter['title']} ({chapter['date'][:10]})")

    # Step 4: List best-rated fictions
    print(f"\n\n{'='*70}")
    print("📊 Browsing best-rated fictions...")
    best_rated = client.list_fictions(category="best-rated", page=1)

    print(f"\nTop 5 Best-Rated Fictions:")
    for idx, fiction in enumerate(best_rated["results"][:5], 1):
        status = ", ".join(fiction["labels"]) if fiction["labels"] else "Active"
        print(f"{idx}. {fiction['title']} - Rating: ⭐{fiction['rating']} [{status}]")

    print(f"\n{'='*70}")
    print("✅ Example complete!")


if __name__ == "__main__":
    main()