Discord APIdiscord.com ↗

"""
Discord Help Center API Client
A practical example of using the Parse API to interact with Discord's Help Center.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Optional


class ParseClient:
    """Client for interacting with the Discord Help Center API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse client with API credentials."""
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "eec89afa-c079-4f37-b701-cfba66d49653"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

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

    def _call(self, endpoint: str, method: str = "POST", **params: Any) -> dict:
        """
        Make an API call to Parse.

        Args:
            endpoint: The API endpoint name
            method: HTTP method (GET or POST)
            **params: Query parameters or payload data

        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "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_articles(
        self, query: str, page: int = 1, per_page: int = 10
    ) -> dict:
        """
        Search Discord Help Center articles by keyword query.

        Args:
            query: Search query string to find relevant help articles
            page: Page number for pagination (default: 1)
            per_page: Number of results per page, between 1 and 100 (default: 10)

        Returns:
            Dictionary with search results including total_count, page info, and results array
        """
        return self._call(
            "search_articles", method="GET", query=query, page=page, per_page=per_page
        )

    def get_article(self, article_id: str) -> dict:
        """
        Retrieve full article content by article ID.

        Args:
            article_id: Numeric article ID from search results (e.g., "360045138571")

        Returns:
            Dictionary with article content including body_text, body_html, and metadata
        """
        return self._call("get_article", method="GET", article_id=article_id)

    def list_categories(self) -> dict:
        """
        List all top-level categories in the Discord Help Center.

        Returns:
            Dictionary with categories array and count
        """
        return self._call("list_categories", method="GET")


def format_article_summary(article: dict) -> str:
    """Format an article summary for display."""
    return f"  • {article['title']}\n    ID: {article['id']} | Votes: {article['vote_sum']} | Updated: {article['updated_at'][:10]}"


def main():
    """Main example demonstrating practical usage of the Discord Help Center API."""
    # Initialize the client
    client = ParseClient()

    print("=" * 80)
    print("Discord Help Center API - Practical Usage Example")
    print("=" * 80)

    # Step 1: List available categories
    print("\n1. Fetching available help categories...")
    categories = client.list_categories()
    print(f"Found {categories['count']} categories:")
    for category in categories["categories"][:5]:  # Show first 5
        print(f"  • {category['name']}")
    if categories["count"] > 5:
        print(f"  ... and {categories['count'] - 5} more")

    # Step 2: Search for articles about voice settings
    search_query = "voice settings"
    print(f"\n2. Searching for articles about '{search_query}'...")
    search_results = client.search_articles(query=search_query, per_page=5)

    print(f"Found {search_results['total_count']} articles (showing {len(search_results['results'])} results):")
    for article in search_results["results"]:
        print(format_article_summary(article))

    # Step 3: Get full content of the first article
    if search_results["results"]:
        first_article = search_results["results"][0]
        article_id = str(first_article["id"])

        print(f"\n3. Fetching full content for article: {first_article['title']}")
        full_article = client.get_article(article_id)

        print(f"\nArticle Details:")
        print(f"  Title: {full_article['title']}")
        print(f"  Author ID: {full_article['author_id']}")
        print(f"  Created: {full_article['created_at'][:10]}")
        print(f"  Last Updated: {full_article['updated_at'][:10]}")
        print(f"  Vote Score: {full_article['vote_sum']} ({full_article['vote_count']} votes)")
        print(f"  Promoted: {'Yes' if full_article['promoted'] else 'No'}")
        print(f"  Labels: {', '.join(full_article['label_names'])}")
        print(f"\nArticle Preview:")
        # Show first 300 characters of the article text
        preview = full_article["body_text"][:300]
        print(f"  {preview}...")

    # Step 4: Search for more specific topics and iterate through results
    print(f"\n4. Searching for 'server creation' articles...")
    server_search = client.search_articles(query="server creation", per_page=3)

    print(f"Found {server_search['total_count']} articles:")
    for idx, article in enumerate(server_search["results"], 1):
        print(f"\n  Article {idx}: {article['title']}")
        print(f"    Snippet: {article['snippet'][:100]}...")
        print(f"    URL: {article['url'][:50]}...")

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


if __name__ == "__main__":
    main()