"""
Base OAuth Client

소셜 미디어 OAuth 클라이언트의 추상 기본 클래스입니다.
"""

from abc import ABC, abstractmethod
from typing import Optional

from app.social.constants import SocialPlatform
from app.social.schemas import OAuthTokenResponse, PlatformUserInfo


class BaseOAuthClient(ABC):
    """
    소셜 미디어 OAuth 클라이언트 추상 기본 클래스

    모든 플랫폼별 OAuth 클라이언트는 이 클래스를 상속받아 구현합니다.

    Attributes:
        platform: 소셜 플랫폼 종류
    """

    platform: SocialPlatform

    @abstractmethod
    def get_authorization_url(self, state: str) -> str:
        """
        OAuth 인증 URL 생성

        Args:
            state: CSRF 방지용 state 토큰

        Returns:
            str: OAuth 인증 페이지 URL
        """
        pass

    @abstractmethod
    async def exchange_code(self, code: str) -> OAuthTokenResponse:
        """
        인가 코드로 액세스 토큰 교환

        Args:
            code: OAuth 인가 코드

        Returns:
            OAuthTokenResponse: 액세스 토큰 및 리프레시 토큰

        Raises:
            OAuthCodeExchangeError: 토큰 교환 실패 시
        """
        pass

    @abstractmethod
    async def refresh_token(self, refresh_token: str) -> OAuthTokenResponse:
        """
        리프레시 토큰으로 액세스 토큰 갱신

        Args:
            refresh_token: 리프레시 토큰

        Returns:
            OAuthTokenResponse: 새 액세스 토큰

        Raises:
            OAuthTokenRefreshError: 토큰 갱신 실패 시
        """
        pass

    @abstractmethod
    async def get_user_info(self, access_token: str) -> PlatformUserInfo:
        """
        플랫폼 사용자 정보 조회

        Args:
            access_token: 액세스 토큰

        Returns:
            PlatformUserInfo: 플랫폼 사용자 정보

        Raises:
            SocialAccountError: 사용자 정보 조회 실패 시
        """
        pass

    @abstractmethod
    async def revoke_token(self, token: str) -> bool:
        """
        토큰 폐기 (연동 해제 시)

        Args:
            token: 폐기할 토큰

        Returns:
            bool: 폐기 성공 여부
        """
        pass

    def is_token_expired(self, expires_in: Optional[int]) -> bool:
        """
        토큰 만료 여부 확인 (만료 10분 전이면 True)

        Args:
            expires_in: 토큰 만료까지 남은 시간(초)

        Returns:
            bool: 갱신 필요 여부
        """
        if expires_in is None:
            return False
        # 만료 10분(600초) 전이면 갱신 필요
        return expires_in <= 600