from abc import ABC, abstractmethod
from typing import Optional

from src.domain.entities.merchant_category import MerchantCategory, MerchantCategoryScript


class MerchantCategoryRepositoryInterface(ABC):
    """Abstract contract for merchant category persistence operations."""

    @abstractmethod
    def get_by_name(self, name: str) -> Optional[MerchantCategory]:
        """Return an existing category matching the given name, or None."""
        ...

    @abstractmethod
    def create_with_script(
        self,
        name: str,
        script_content: str,
        user_id: int,
    ) -> MerchantCategory:
        """Create a new merchant category and persist its verification script.

        Returns the newly-created MerchantCategory entity (with id populated).
        """
        ...

    @abstractmethod
    def get_script_by_category(self, category_id: int) -> Optional[MerchantCategoryScript]:
        """Return the current verification script for a category, or None."""
        ...

    @abstractmethod
    def upsert_script(
        self,
        category_id: int,
        script_content: str,
        user_id: int,
    ) -> MerchantCategoryScript:
        """Update an existing verification script (archiving the old one first),
        or create a new one if none exists yet.

        Returns the saved MerchantCategoryScript entity.
        """
        ...