"""
API 基础模块

定义了 API 调用的基础接口和统一处理逻辑。
"""
from typing import Any, Dict, Optional, TYPE_CHECKING

from ..utils.logger import logger

if TYPE_CHECKING:
    from ..ws import WS


class BaseAPI:
    """
    API 基础类，提供了统一的 `call_api` 方法，包含日志记录和异常处理。
    """
    _ws: "WS"
    self_id: int

    def __init__(self, ws_client: "WS", self_id: int):
        self._ws = ws_client
        self.self_id = self_id

    async def call_api(self, action: str, params: Optional[Dict[str, Any]] = None) -> Any:
        """
        调用 OneBot v11 API，并提供统一的日志和异常处理。

        :param action: API 动作名称
        :param params: API 参数
        :return: API 响应结果的数据部分
        :raises Exception: 当 API 调用失败或发生网络错误时
        """
        if params is None:
            params = {}
        
        try:
            logger.debug(f"调用API -> action: {action}, params: {params}")
            response = await self._ws.call_api(action, params)
            logger.debug(f"API响应 <- {response}")

            if response.get("status") == "failed":
                logger.warning(f"API调用失败: {response}")
            
            return response.get("data")

        except Exception as e:
            logger.error(f"API调用异常: action={action}, params={params}, error={e}")
            raise