from abc import ABC, abstractmethod
from typing import Dict, List, Tuple

class BaseStorageProvider(ABC):
    """
    Abstract Base Class for all Document Storage Providers (SharePoint, Google Drive, Local, NAS, etc.)
    Any new storage source must implement these methods to be seamlessly integrated into the ingestion pipeline.
    """
    
    @abstractmethod
    def fetch_changes(self, sync_state: Dict) -> Tuple[List[Dict], Dict]:
        """
        Fetch incremental changes (new, updated, or deleted files).
        
        Args:
            sync_state (Dict): The last known synchronization state/token.
            
        Returns:
            Tuple[List[Dict], Dict]: 
                - A list of standardized item dictionaries.
                - The new sync state to be saved for the next run.
        """
        pass

    @abstractmethod
    def download_file(self, target_item: Dict) -> bytes:
        """
        Download the raw file bytes for a given item.
        
        Args:
            target_item (Dict): The standardized item dictionary returned by fetch_changes.
            
        Returns:
            bytes: The raw file content.
        """
        pass

    @abstractmethod
    def get_item_details(self, item_id: str) -> Dict:
        """
        Get full item details including webUrl and downloadUrl.
        
        Args:
            item_id (str): The item ID from fetch_changes.
            
        Returns:
            Dict: Full item details with links.
        """
        pass

    @abstractmethod
    def get_item_permissions(self, item_id: str) -> List[str]:
        """
        Get permissions for an item. Returns list of user/group emails or IDs.
        
        Args:
            item_id (str): The item ID from fetch_changes.
            
        Returns:
            List[str]: List of user/group identifiers. ["*"] means everyone can access.
        """
        pass