mcphub/plugins/wordpress/handlers/reports.py

"""Reports Handler - manages WooCommerce reporting and analytics"""

import json
from typing import Any

from plugins.wordpress.client import WordPressClient


def get_tool_specifications() -> list[dict[str, Any]]:
    """Return tool specifications for ToolGenerator"""
    return [
        # === WOOCOMMERCE REPORTS ===
        {
            "name": "get_sales_report",
            "method_name": "get_sales_report",
            "description": "Get WooCommerce sales report. Returns sales data with totals and date ranges. Note: WooCommerce v3 API has limited reporting capabilities.",
            "schema": {
                "type": "object",
                "properties": {
                    "period": {
                        "type": "string",
                        "description": "Report period (week, month, last_month, year)",
                        "enum": ["week", "month", "last_month", "year"],
                        "default": "week",
                    },
                    "date_min": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date for report (ISO 8601 format, e.g., '2024-01-01')",
                    },
                    "date_max": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date for report (ISO 8601 format, e.g., '2024-12-31')",
                    },
                },
            },
            "scope": "read",
        },
        {
            "name": "get_top_sellers",
            "method_name": "get_top_sellers",
            "description": "Get top selling products report. Returns products with highest sales quantities.",
            "schema": {
                "type": "object",
                "properties": {
                    "period": {
                        "type": "string",
                        "description": "Report period (week, month, last_month, year)",
                        "enum": ["week", "month", "last_month", "year"],
                        "default": "week",
                    },
                    "date_min": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date for report (ISO 8601 format)",
                    },
                    "date_max": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date for report (ISO 8601 format)",
                    },
                },
            },
            "scope": "read",
        },
        {
            "name": "get_customer_report",
            "method_name": "get_customer_report",
            "description": "Get customer statistics report. Returns customer count and spending data. Falls back to customer list if reports endpoint unavailable.",
            "schema": {
                "type": "object",
                "properties": {
                    "period": {
                        "type": "string",
                        "description": "Report period (week, month, last_month, year)",
                        "enum": ["week", "month", "last_month", "year"],
                        "default": "week",
                    },
                    "date_min": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date for report (ISO 8601 format)",
                    },
                    "date_max": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date for report (ISO 8601 format)",
                    },
                },
            },
            "scope": "read",
        },
    ]


class ReportsHandler:
    """Handle WooCommerce reporting operations"""

    def __init__(self, client: WordPressClient):
        """
        Initialize reports handler.

        Args:
            client: WordPress API client instance
        """
        self.client = client

    # === WOOCOMMERCE REPORTS ===

    async def get_sales_report(
        self, period: str = "week", date_min: str | None = None, date_max: str | None = None
    ) -> str:
        """
        Get WooCommerce sales report.

        Args:
            period: Report period (week, month, last_month, year)
            date_min: Start date for report (ISO 8601 format, e.g., '2024-01-01')
            date_max: End date for report (ISO 8601 format, e.g., '2024-12-31')

        Returns:
            JSON string with sales report data

        Note:
            WooCommerce v3 API has limited reporting capabilities.
            For advanced analytics, use WooCommerce Analytics extension.
        """
        try:
            params = {"period": period}
            if date_min:
                params["date_min"] = date_min
            if date_max:
                params["date_max"] = date_max

            report_data = await self.client.get(
                "reports/sales", params=params, use_woocommerce=True
            )

            # Format the response based on what the API returns
            result = {
                "period": period,
                "sales_data": report_data if isinstance(report_data, list) else [report_data],
                "note": "WooCommerce v3 API has limited reporting. For advanced analytics, use WooCommerce Analytics extension.",
            }

            return json.dumps(result, indent=2)
        except Exception as e:
            error_msg = str(e)
            # Check if reports endpoint is not available
            if "404" in error_msg or "not found" in error_msg.lower():
                return json.dumps(
                    {
                        "error": "Sales reports endpoint not available",
                        "message": "WooCommerce v3 API has limited reporting capabilities. Consider using WooCommerce Analytics or custom queries.",
                        "details": error_msg,
                    },
                    indent=2,
                )
            return json.dumps(
                {"error": str(e), "message": f"Failed to get sales report: {str(e)}"}, indent=2
            )

    async def get_top_sellers(
        self, period: str = "week", date_min: str | None = None, date_max: str | None = None
    ) -> str:
        """
        Get top selling products report.

        Args:
            period: Report period (week, month, last_month, year)
            date_min: Start date for report (ISO 8601 format)
            date_max: End date for report (ISO 8601 format)

        Returns:
            JSON string with top sellers data
        """
        try:
            params = {"period": period}
            if date_min:
                params["date_min"] = date_min
            if date_max:
                params["date_max"] = date_max

            top_sellers = await self.client.get(
                "reports/top_sellers", params=params, use_woocommerce=True
            )

            result = {
                "period": period,
                "total_products": len(top_sellers) if isinstance(top_sellers, list) else 0,
                "top_sellers": [
                    {
                        "product_id": item.get("product_id"),
                        "title": item.get("title"),
                        "quantity": item.get("quantity", 0),
                    }
                    for item in (top_sellers if isinstance(top_sellers, list) else [])
                ],
            }

            return json.dumps(result, indent=2)
        except Exception as e:
            error_msg = str(e)
            if "404" in error_msg or "not found" in error_msg.lower():
                return json.dumps(
                    {
                        "error": "Top sellers endpoint not available",
                        "message": "WooCommerce v3 API has limited reporting capabilities.",
                        "details": error_msg,
                    },
                    indent=2,
                )
            return json.dumps(
                {"error": str(e), "message": f"Failed to get top sellers: {str(e)}"}, indent=2
            )

    async def get_customer_report(
        self, period: str = "week", date_min: str | None = None, date_max: str | None = None
    ) -> str:
        """
        Get customer statistics report.

        Args:
            period: Report period (week, month, last_month, year)
            date_min: Start date for report (ISO 8601 format)
            date_max: End date for report (ISO 8601 format)

        Returns:
            JSON string with customer report data

        Note:
            Falls back to customer list endpoint if reports endpoint is unavailable.
        """
        try:
            params = {"period": period}
            if date_min:
                params["date_min"] = date_min
            if date_max:
                params["date_max"] = date_max

            try:
                customer_data = await self.client.get(
                    "reports/customers", params=params, use_woocommerce=True
                )

                result = {
                    "period": period,
                    "customer_data": (
                        customer_data if isinstance(customer_data, list) else [customer_data]
                    ),
                    "note": "Customer reporting may be limited in WooCommerce v3 API.",
                }

                return json.dumps(result, indent=2)
            except Exception as report_error:
                # Check if it's a 404 error - use fallback
                if "404" in str(report_error) or "not found" in str(report_error).lower():
                    return await self._get_customer_report_fallback()
                raise report_error

        except Exception as e:
            return json.dumps(
                {"error": str(e), "message": f"Failed to get customer report: {str(e)}"}, indent=2
            )

    async def _get_customer_report_fallback(self) -> str:
        """
        Fallback method when customer reports endpoint is not available.

        Uses the customers list endpoint to generate basic statistics.

        Returns:
            JSON string with basic customer statistics
        """
        try:
            # Use customers list to generate basic stats
            customers = await self.client.get(
                "customers", params={"per_page": 100}, use_woocommerce=True
            )

            # Calculate basic stats
            total_customers = len(customers) if isinstance(customers, list) else 0
            total_spent = (
                sum(float(c.get("total_spent", 0)) for c in customers)
                if isinstance(customers, list)
                else 0
            )
            avg_spent = total_spent / total_customers if total_customers > 0 else 0

            result = {
                "total_customers": total_customers,
                "total_spent": f"{total_spent:.2f}",
                "average_spent_per_customer": f"{avg_spent:.2f}",
                "note": "Generated from customer list (fallback method). For detailed analytics, use WooCommerce Analytics.",
            }

            return json.dumps(result, indent=2)
        except Exception as e:
            return json.dumps(
                {
                    "error": str(e),
                    "message": "Customer report and fallback both unavailable",
                    "details": str(e),
                },
                indent=2,
            )