POEditor MCP Server

"""Utility functions for POEditor MCP server."""

from typing import Any, Dict, List, Optional
from datetime import datetime
import json


def format_project_summary(project: Dict[str, Any]) -> str:
    """Format a project summary for display.
    
    Args:
        project: Project data from POEditor API
        
    Returns:
        Formatted project summary
    """
    name = project.get("name", "Unknown")
    project_id = project.get("id", "Unknown")
    description = project.get("description", "No description")
    
    return f"Project: {name} (ID: {project_id})\nDescription: {description}"


def format_language_stats(language: Dict[str, Any]) -> str:
    """Format language statistics for display.
    
    Args:
        language: Language data from POEditor API
        
    Returns:
        Formatted language statistics
    """
    name = language.get("name", "Unknown")
    code = language.get("code", "Unknown")
    percentage = language.get("percentage", 0)
    
    return f"Language: {name} ({code}) - {percentage}% complete"


def format_term_list(terms: List[Dict[str, Any]], limit: Optional[int] = None) -> str:
    """Format a list of terms for display.
    
    Args:
        terms: List of terms from POEditor API
        limit: Optional limit on number of terms to display
        
    Returns:
        Formatted terms list
    """
    if not terms:
        return "No terms found."
    
    display_terms = terms[:limit] if limit else terms
    formatted = []
    
    for term in display_terms:
        term_text = term.get("term", "Unknown term")
        context = term.get("context", "")
        
        line = f"• {term_text}"
        if context:
            line += f" (Context: {context})"
        
        formatted.append(line)
    
    result = "\n".join(formatted)
    
    if limit and len(terms) > limit:
        result += f"\n... and {len(terms) - limit} more terms"
    
    return result


def format_translation_stats(stats: Dict[str, Any]) -> str:
    """Format translation statistics for display.
    
    Args:
        stats: Translation statistics from POEditor API
        
    Returns:
        Formatted statistics
    """
    total = stats.get("terms", 0)
    translated = stats.get("translated", 0)
    percentage = stats.get("percentage", 0)
    
    return f"Translation Progress: {translated}/{total} terms ({percentage}% complete)"


def safe_json_dumps(data: Any, indent: int = 2) -> str:
    """Safely serialize data to JSON.
    
    Args:
        data: Data to serialize
        indent: JSON indentation
        
    Returns:
        JSON string
    """
    try:
        return json.dumps(data, indent=indent, ensure_ascii=False)
    except (TypeError, ValueError) as e:
        return f"Error serializing data: {e}"


def timestamp_now() -> str:
    """Get current timestamp as formatted string.
    
    Returns:
        Current timestamp in ISO format
    """
    return datetime.now().isoformat()


def validate_project_id(project_id: Any) -> str:
    """Validate and convert project ID to string.
    
    Args:
        project_id: Project ID to validate
        
    Returns:
        Valid project ID as string
        
    Raises:
        ValueError: If project ID is invalid
    """
    if project_id is None:
        raise ValueError("Project ID is required")
    
    try:
        return str(project_id)
    except Exception:
        raise ValueError("Invalid project ID format")


def validate_language_code(language_code: Any) -> str:
    """Validate language code.
    
    Args:
        language_code: Language code to validate
        
    Returns:
        Valid language code as string
        
    Raises:
        ValueError: If language code is invalid
    """
    if not language_code:
        raise ValueError("Language code is required")
    
    code = str(language_code).strip().lower()
    
    if not code or len(code) < 2:
        raise ValueError("Language code must be at least 2 characters")
    
    return code