src/interfaces/plugin_interfaces.py

"""
Plugin system interfaces.
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional, List
from dataclasses import dataclass
from enum import Enum


class PluginType(Enum):
    """Types of plugins supported."""
    NPC = "npc"
    SERVICE = "service"
    UI = "ui"
    EVENT = "event"
    DATA = "data"
    NETWORK = "network"


@dataclass
class PluginMetadata:
    """Plugin metadata information."""
    id: str
    name: str
    version: str
    description: str
    author: str
    plugin_type: PluginType
    dependencies: List[str]
    config: Dict[str, Any]


class IPlugin(ABC):
    """Base interface for all plugins."""
    
    @property
    @abstractmethod
    def metadata(self) -> PluginMetadata:
        """Get plugin metadata."""
        pass
    
    @abstractmethod
    def initialize(self, context: Dict[str, Any]) -> bool:
        """Initialize the plugin with game context."""
        pass
    
    @abstractmethod
    def shutdown(self) -> bool:
        """Shutdown the plugin and cleanup resources."""
        pass
    
    @abstractmethod
    def get_status(self) -> Dict[str, Any]:
        """Get current plugin status."""
        pass
    
    def on_player_join(self, player_id: str) -> None:
        """Called when a player joins the game."""
        pass
    
    def on_player_leave(self, player_id: str) -> None:
        """Called when a player leaves the game."""
        pass
    
    def on_chat_message(self, sender_id: str, message: str, message_type: str) -> None:
        """Called when a chat message is sent."""
        pass


class INPCPlugin(IPlugin):
    """Interface for NPC plugins."""
    
    @abstractmethod
    def get_npc_response(self, npc_id: str, message: str, player_id: str = None) -> str:
        """Generate NPC response."""
        pass
    
    @abstractmethod
    def get_npc_data(self) -> Dict[str, Any]:
        """Get NPC configuration data."""
        pass


class IServicePlugin(IPlugin):
    """Interface for service plugins."""
    
    @abstractmethod
    def get_service_name(self) -> str:
        """Get the service name this plugin provides."""
        pass
    
    @abstractmethod
    def get_service_instance(self) -> Any:
        """Get the service instance."""
        pass


class IUIPlugin(IPlugin):
    """Interface for UI plugins."""
    
    @abstractmethod
    def get_ui_component(self) -> Any:
        """Get UI component (Gradio component)."""
        pass
    
    @abstractmethod
    def get_tab_name(self) -> str:
        """Get tab name for UI."""
        pass


class IEventPlugin(IPlugin):
    """Interface for event-based plugins."""
    
    @abstractmethod
    def get_event_handlers(self) -> Dict[str, callable]:
        """Get event handlers dictionary."""
        pass


class IDataPlugin(IPlugin):
    """Interface for data storage plugins."""
    
    @abstractmethod
    def save_data(self, key: str, data: Any) -> bool:
        """Save data with given key."""
        pass
    
    @abstractmethod
    def load_data(self, key: str) -> Optional[Any]:
        """Load data by key."""
        pass
    
    @abstractmethod
    def delete_data(self, key: str) -> bool:
        """Delete data by key."""
        pass


class INetworkPlugin(IPlugin):
    """Interface for network-based plugins."""
    
    @abstractmethod
    def handle_request(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
        """Handle network request."""
        pass
    
    @abstractmethod
    def get_endpoint(self) -> str:
        """Get network endpoint this plugin handles."""
        pass


class IWeatherPlugin(IPlugin):
    """Interface for weather system plugins."""
    
    @abstractmethod
    def get_weather_info(self) -> Dict[str, Any]:
        """Get current weather information."""
        pass
    
    @abstractmethod
    def update_weather(self) -> Dict[str, Any]:
        """Update weather conditions."""
        pass
    
    @abstractmethod
    def apply_weather_effects(self, player_data: Dict[str, Any]) -> Dict[str, Any]:
        """Apply weather effects to player."""
        pass


class IChatPlugin(IPlugin):
    """Interface for chat enhancement plugins."""
    
    @abstractmethod
    def process_message(self, player_id: str, message: str, channel: str = "global") -> Dict[str, Any]:
        """Process and enhance chat messages."""
        pass
    
    @abstractmethod
    def get_available_commands(self) -> List[Dict[str, str]]:
        """Get list of available chat commands."""
        pass
    
    @abstractmethod
    def get_chat_channels(self) -> Dict[str, Dict[str, str]]:
        """Get available chat channels."""
        pass


class IEconomyPlugin(IPlugin):
    """Interface for economy and trading plugins."""
    
    @abstractmethod
    def initiate_trade(self, player1_id: str, player2_id: str, player1_pos: tuple, player2_pos: tuple) -> Dict[str, Any]:
        """Initiate a trade between two players."""
        pass
    
    @abstractmethod
    def create_marketplace_listing(self, player_id: str, item_id: str, quantity: int, price: int) -> Dict[str, Any]:
        """Create a marketplace listing."""
        pass
    
    @abstractmethod
    def get_marketplace_listings(self, item_filter: Optional[str] = None) -> List[Dict[str, Any]]:
        """Get marketplace listings."""
        pass
    
    @abstractmethod
    def get_tradeable_items(self) -> Dict[str, Dict[str, Any]]:
        """Get list of tradeable items."""  
        pass


# Plugin exceptions
class PluginError(Exception):
    """Base plugin exception."""
    pass


class PluginInitializationError(PluginError):
    """Plugin initialization failed."""
    pass


class PluginDependencyError(PluginError):
    """Plugin dependency error."""
    pass


class PluginConfigurationError(PluginError):
    """Plugin configuration error."""
    pass