# Copyright (c) 2025 Patrick Motsch
# All rights reserved.
"""Abstract base classes for the Provider-Connector architecture (1:n).

One ProviderConnector per vendor (e.g. MsftConnector, GoogleConnector).
Each ProviderConnector exposes n ServiceAdapters (e.g. SharepointAdapter, OutlookAdapter).
All ServiceAdapters share the same access token from the UserConnection.
"""

from abc import ABC, abstractmethod
from typing import List, Optional


class ServiceAdapter(ABC):
    """Standardized operations for a single service of a provider."""

    @abstractmethod
    async def browse(self, path: str, filter: Optional[str] = None) -> list:
        """List items (files/folders) at the given path."""
        ...

    @abstractmethod
    async def download(self, path: str) -> bytes:
        """Download a file and return its content bytes."""
        ...

    @abstractmethod
    async def upload(self, path: str, data: bytes, fileName: str) -> dict:
        """Upload a file to the given path. Returns metadata of the created entry."""
        ...

    @abstractmethod
    async def search(self, query: str, path: Optional[str] = None) -> list:
        """Search for items matching the query."""
        ...


class ProviderConnector(ABC):
    """One connector per provider. Manages a UserConnection + token.
    Provides access to n services of the provider."""

    def __init__(self, connection, accessToken: str):
        self.connection = connection
        self.accessToken = accessToken

    @abstractmethod
    def getAvailableServices(self) -> List[str]:
        """Which services does this provider offer?"""
        ...

    @abstractmethod
    def getServiceAdapter(self, service: str) -> ServiceAdapter:
        """Return the ServiceAdapter for a specific service."""
        ...