"""
ExternalStore - 外部服务相关的配置存储抽象

包含 Platform, AuthMethod, McpServerSpec, McpResourceDescriptor 等外部服务配置类。
来自 schema/external.py
"""

from abc import ABC, abstractmethod
from typing import Optional, List, Dict, Any
from turbo_agent_core.schema.external import (
    Platform,
    AuthMethod,
    McpServerSpec,
    McpResourceDescriptor,
)


class ExternalStore(ABC):
    """
    外部服务相关的配置存储抽象类。
    
    所有方法均支持 **kwargs 参数，用于实现侧传入鉴权信息。
    """

    # ========== Platform CRUD ==========
    @abstractmethod
    async def get_platform(
        self, 
        platform_id: str, 
        **kwargs
    ) -> Optional[Platform]:
        """
        根据 ID 获取 Platform。

        Args:
            platform_id: Platform 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def get_platform_by_name_en(
        self,
        project_id: str,
        name_en: str,
        **kwargs
    ) -> Optional[Platform]:
        """
        通过 name_en 和 project_id 获取 Platform。

        Args:
            project_id: 所属项目 ID (org_projectid 格式)
            name_en: Platform 英文名
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_platform(
        self, 
        platform: Platform, 
        **kwargs
    ) -> str:
        """
        保存 Platform，返回 Platform ID。

        Args:
            platform: Platform 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_platforms(
        self, 
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[Platform]:
        """
        列出 Platforms。

        Args:
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_platform(
        self, 
        platform_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 Platform。

        Args:
            platform_id: Platform 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== AuthMethod CRUD ==========
    @abstractmethod
    async def get_auth_method(
        self, 
        method_id: str, 
        **kwargs
    ) -> Optional[AuthMethod]:
        """
        根据 ID 获取 AuthMethod。

        Args:
            method_id: AuthMethod 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def create_auth_method(
        self,
        platform_id: str,
        data: Dict[str, Any],
        creator_id: str,
        **kwargs
    ) -> AuthMethod:
        """
        创建 AuthMethod。

        Args:
            platform_id: 所属 Platform ID
            data: AuthMethod 数据字典，包含 name, auth_type, description 等字段
            creator_id: 创建者用户 ID
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def update_auth_method(
        self,
        method_id: str,
        data: Dict[str, Any],
        **kwargs
    ) -> Optional[AuthMethod]:
        """
        更新 AuthMethod。

        Args:
            method_id: AuthMethod 唯一标识
            data: 要更新的字段字典
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_auth_method(
        self, 
        auth_method: AuthMethod, 
        **kwargs
    ) -> str:
        """
        保存 AuthMethod，返回 Method ID。

        Args:
            auth_method: AuthMethod 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_auth_methods(
        self, 
        platform_id: str,
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[AuthMethod]:
        """
        列出指定 Platform 的 AuthMethods。

        Args:
            platform_id: Platform ID
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_auth_method(
        self, 
        method_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 AuthMethod。

        Args:
            method_id: AuthMethod 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== McpServerSpec CRUD ==========
    @abstractmethod
    async def get_mcp_server(
        self, 
        server_id: str, 
        **kwargs
    ) -> Optional[McpServerSpec]:
        """
        根据 ID 获取 McpServerSpec。

        Args:
            server_id: McpServerSpec 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_mcp_server(
        self, 
        server: McpServerSpec, 
        **kwargs
    ) -> str:
        """
        保存 McpServerSpec，返回 Server ID。

        Args:
            server: McpServerSpec 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_mcp_servers(
        self, 
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[McpServerSpec]:
        """
        列出 McpServerSpecs。

        Args:
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_mcp_server(
        self, 
        server_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 McpServerSpec。

        Args:
            server_id: McpServerSpec 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== McpResourceDescriptor CRUD ==========
    @abstractmethod
    async def get_mcp_resource(
        self, 
        resource_id: str, 
        **kwargs
    ) -> Optional[McpResourceDescriptor]:
        """
        根据 ID 获取 McpResourceDescriptor。

        Args:
            resource_id: McpResourceDescriptor 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_mcp_resource(
        self, 
        resource: McpResourceDescriptor, 
        **kwargs
    ) -> str:
        """
        保存 McpResourceDescriptor，返回 Resource ID。

        Args:
            resource: McpResourceDescriptor 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_mcp_resources(
        self, 
        server_id: Optional[str] = None,
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[McpResourceDescriptor]:
        """
        列出 McpResourceDescriptors。

        Args:
            server_id: 可选的 MCP Server ID 过滤
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_mcp_resource(
        self, 
        resource_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 McpResourceDescriptor。

        Args:
            resource_id: McpResourceDescriptor 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass
