mcphub/plugins/wordpress/client.py

"""
WordPress REST API Client

Handles all HTTP communication with WordPress REST API.
Separates API communication from business logic.
"""

import base64
import json
import logging
from typing import Any

import aiohttp


class ConfigurationError(Exception):
    """Raised when site configuration is invalid or incomplete."""

    pass


class AuthenticationError(Exception):
    """Raised when authentication fails (401/403)."""

    pass


class WordPressClient:
    """
    WordPress REST API client for HTTP communication.

    Handles authentication, request formatting, and error handling
    for all WordPress and WooCommerce API endpoints.
    """

    def __init__(self, site_url: str, username: str, app_password: str):
        """
        Initialize WordPress API client.

        Args:
            site_url: WordPress site URL (e.g., https://example.com)
            username: WordPress username
            app_password: WordPress application password

        Raises:
            ConfigurationError: If required parameters are missing or invalid
        """
        # Validate required parameters
        if not site_url:
            raise ConfigurationError(
                "Site URL is not configured. "
                "Please set the URL environment variable (e.g., WORDPRESS_SITE1_URL)."
            )
        if not username:
            raise ConfigurationError(
                "Username is not configured. "
                "Please set the USERNAME environment variable (e.g., WORDPRESS_SITE1_USERNAME)."
            )
        if not app_password:
            raise ConfigurationError(
                "App password is not configured. "
                "Please set the APP_PASSWORD environment variable (e.g., WORDPRESS_SITE1_APP_PASSWORD)."
            )

        self.site_url = site_url.rstrip("/")
        self.api_base = f"{self.site_url}/wp-json/wp/v2"
        self.wc_api_base = f"{self.site_url}/wp-json/wc/v3"
        self.username = username
        self.app_password = app_password

        # Initialize logger
        self.logger = logging.getLogger(f"WordPressClient.{site_url}")

        # Create auth header
        credentials = f"{self.username}:{self.app_password}"
        token = base64.b64encode(credentials.encode()).decode()
        self.auth_header = f"Basic {token}"

    async def request(
        self,
        method: str,
        endpoint: str,
        params: dict | None = None,
        json_data: dict | None = None,
        data: Any | None = None,
        headers_override: dict | None = None,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make authenticated request to WordPress REST API.

        Args:
            method: HTTP method (GET, POST, PUT, DELETE, PATCH)
            endpoint: API endpoint (without base URL)
            params: Query parameters
            json_data: JSON body data
            data: Raw data or FormData for file uploads
            headers_override: Override default headers
            use_custom_namespace: If True, use wp-json root instead of wp/v2
            use_woocommerce: If True, use WooCommerce API base

        Returns:
            Dict: API response as JSON

        Raises:
            Exception: On API errors with status code and message
        """
        # Build URL based on endpoint type
        if use_custom_namespace:
            # For custom namespaces like seo-api-bridge/v1
            url = f"{self.site_url}/wp-json/{endpoint}"
        elif use_woocommerce:
            # For WooCommerce endpoints
            url = f"{self.wc_api_base}/{endpoint}"
        else:
            # Standard WordPress endpoints
            url = f"{self.api_base}/{endpoint}"

        # Setup headers
        headers = {"Authorization": self.auth_header}
        if headers_override:
            headers.update(headers_override)

        # Filter out None, empty strings, and empty lists from params
        # to avoid WordPress/WooCommerce API validation errors
        # Phase K.2.1: Enhanced parameter filtering
        def should_include(v):
            """Check if value should be included in request."""
            if v is None:
                return False
            if isinstance(v, str) and v.strip() == "":
                return False
            return not (isinstance(v, list) and len(v) == 0)

        if params:
            params = {k: v for k, v in params.items() if should_include(v)}

        # Filter None and empty values from JSON data for POST/PUT/PATCH requests
        if json_data:
            json_data = {k: v for k, v in json_data.items() if should_include(v)}

        # Make request
        async with (
            aiohttp.ClientSession() as session,
            session.request(
                method, url, params=params, json=json_data, data=data, headers=headers
            ) as response,
        ):
            # Handle errors with structured error messages
            if response.status >= 400:
                error_text = await response.text()

                # Parse structured error response
                error_info = self._parse_error_response(
                    response.status, error_text, use_woocommerce
                )

                # Log the error for debugging
                self.logger.error(
                    f"API error: {error_info['error_code']} - {error_info['message']}"
                )

                # Raise appropriate exception
                if response.status in (401, 403):
                    raise AuthenticationError(
                        f"[{error_info['error_code']}] {error_info['message']}"
                    )

                raise Exception(f"[{error_info['error_code']}] {error_info['message']}")

            # Return JSON response
            return await response.json()

    def _parse_error_response(
        self, status_code: int, error_text: str, use_woocommerce: bool = False
    ) -> dict[str, Any]:
        """
        Parse error response and return structured error info.

        Args:
            status_code: HTTP status code
            error_text: Raw error response text
            use_woocommerce: Whether this is a WooCommerce API call

        Returns:
            Dict with error_code, message, and details
        """
        # Try to parse as JSON
        try:
            error_json = json.loads(error_text)
            wp_error_code = error_json.get("code", "unknown_error")
            wp_message = error_json.get("message", error_text)
        except (json.JSONDecodeError, TypeError):
            wp_error_code = "unknown_error"
            wp_message = error_text

        # Map status codes to structured error codes
        error_codes = {
            400: "BAD_REQUEST",
            401: "AUTH_FAILED",
            403: "ACCESS_DENIED",
            404: "NOT_FOUND",
            405: "METHOD_NOT_ALLOWED",
            409: "CONFLICT",
            422: "VALIDATION_ERROR",
            429: "RATE_LIMITED",
            500: "SERVER_ERROR",
            502: "BAD_GATEWAY",
            503: "SERVICE_UNAVAILABLE",
        }

        error_code = error_codes.get(status_code, f"HTTP_{status_code}")

        # Create user-friendly messages for common errors
        # Phase K.2.1: Enhanced error messages with helpful hints
        friendly_messages = {
            400: (
                f"Invalid request parameters. {wp_message}. "
                "Hints: Check parameter types match the expected format. "
                'For categories/tags use IDs (e.g., [62] or "62,63"). '
                "For billing/shipping use JSON objects."
            ),
            401: (
                "Authentication failed. Please verify: "
                "1) Username is correct, "
                "2) Application Password is valid, "
                "3) User has required permissions. "
                f"Details: {wp_message}"
            ),
            403: (
                "Access denied. The user does not have permission for this action. "
                "Some operations (like coupons) require admin-level WooCommerce permissions. "
                f"Details: {wp_message}"
            ),
            404: (
                "Resource not found. The requested endpoint or item does not exist. "
                f"Details: {wp_message}"
            ),
        }

        # Add WooCommerce-specific hints
        if use_woocommerce and status_code == 401:
            friendly_messages[401] = (
                "WooCommerce authentication failed. Please verify: "
                "1) WooCommerce REST API is enabled, "
                "2) Application Password has WooCommerce permissions, "
                "3) User has 'manage_woocommerce' capability. "
                f"Details: {wp_message}"
            )

        message = friendly_messages.get(status_code, f"{wp_message}")

        return {
            "error_code": error_code,
            "status_code": status_code,
            "message": message,
            "wp_error_code": wp_error_code,
            "raw_response": error_text[:500],  # Limit raw response length
        }

    async def get(
        self,
        endpoint: str,
        params: dict | None = None,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make GET request.

        Args:
            endpoint: API endpoint
            params: Query parameters
            use_custom_namespace: Use custom namespace instead of wp/v2
            use_woocommerce: Use WooCommerce API base

        Returns:
            Dict: API response
        """
        return await self.request(
            "GET",
            endpoint,
            params=params,
            use_custom_namespace=use_custom_namespace,
            use_woocommerce=use_woocommerce,
        )

    async def post(
        self,
        endpoint: str,
        json_data: dict | None = None,
        data: Any | None = None,
        headers_override: dict | None = None,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make POST request.

        Args:
            endpoint: API endpoint
            json_data: JSON body data
            data: Raw data or FormData for file uploads
            headers_override: Override default headers
            use_custom_namespace: Use custom namespace instead of wp/v2
            use_woocommerce: Use WooCommerce API base

        Returns:
            Dict: API response
        """
        return await self.request(
            "POST",
            endpoint,
            json_data=json_data,
            data=data,
            headers_override=headers_override,
            use_custom_namespace=use_custom_namespace,
            use_woocommerce=use_woocommerce,
        )

    async def put(
        self,
        endpoint: str,
        json_data: dict,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make PUT request.

        Args:
            endpoint: API endpoint
            json_data: JSON body data
            use_custom_namespace: Use custom namespace instead of wp/v2
            use_woocommerce: Use WooCommerce API base

        Returns:
            Dict: API response
        """
        return await self.request(
            "PUT",
            endpoint,
            json_data=json_data,
            use_custom_namespace=use_custom_namespace,
            use_woocommerce=use_woocommerce,
        )

    async def patch(
        self,
        endpoint: str,
        json_data: dict,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make PATCH request.

        Args:
            endpoint: API endpoint
            json_data: JSON body data
            use_custom_namespace: Use custom namespace instead of wp/v2
            use_woocommerce: Use WooCommerce API base

        Returns:
            Dict: API response
        """
        return await self.request(
            "PATCH",
            endpoint,
            json_data=json_data,
            use_custom_namespace=use_custom_namespace,
            use_woocommerce=use_woocommerce,
        )

    async def delete(
        self,
        endpoint: str,
        params: dict | None = None,
        use_custom_namespace: bool = False,
        use_woocommerce: bool = False,
    ) -> dict[str, Any]:
        """
        Make DELETE request.

        Args:
            endpoint: API endpoint
            params: Query parameters
            use_custom_namespace: Use custom namespace instead of wp/v2
            use_woocommerce: Use WooCommerce API base

        Returns:
            Dict: API response
        """
        return await self.request(
            "DELETE",
            endpoint,
            params=params,
            use_custom_namespace=use_custom_namespace,
            use_woocommerce=use_woocommerce,
        )

    async def check_woocommerce(self) -> dict[str, Any]:
        """
        Check if WooCommerce is installed and accessible.

        Returns:
            Dict with 'available' bool and version info
        """
        try:
            # Try to access WooCommerce system status endpoint
            response = await self.get("system_status", use_woocommerce=True)
            return {
                "available": True,
                "version": response.get("environment", {}).get("version", "unknown"),
            }
        except Exception:
            return {"available": False, "version": None}

    async def check_site_health(self) -> dict[str, Any]:
        """
        Check WordPress site health and accessibility.

        Returns:
            Dict with health status information
        """
        try:
            async with aiohttp.ClientSession() as session:
                async with session.get(f"{self.site_url}/wp-json") as response:
                    if response.status == 200:
                        data = await response.json()
                        return {
                            "healthy": True,
                            "accessible": True,
                            "name": data.get("name", "Unknown"),
                            "description": data.get("description", "Unknown"),
                            "url": data.get("url", self.site_url),
                            "routes": len(data.get("routes", {})),
                        }
                    else:
                        return {
                            "healthy": False,
                            "accessible": False,
                            "message": f"Site returned status {response.status}",
                        }
        except Exception as e:
            return {
                "healthy": False,
                "accessible": False,
                "message": f"Health check failed: {str(e)}",
            }