orion/app/modules/contracts/cms.py

# app/modules/contracts/cms.py
"""
CMS module contracts.

Defines the interface for content management functionality that other
modules can depend on without importing the concrete implementation.
"""

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from sqlalchemy.orm import Session


@runtime_checkable
class ContentServiceProtocol(Protocol):
    """
    Protocol for content page service.

    Defines the interface for retrieving and managing content pages
    with three-tier resolution (platform > vendor default > vendor override).
    """

    def get_page_for_vendor(
        self,
        db: "Session",
        platform_id: int,
        slug: str,
        vendor_id: int | None = None,
        include_unpublished: bool = False,
    ) -> object | None:
        """
        Get content page with three-tier resolution.

        Resolution order:
        1. Vendor override (platform_id + vendor_id + slug)
        2. Vendor default (platform_id + vendor_id=NULL + is_platform_page=False + slug)

        Args:
            db: Database session
            platform_id: Platform ID
            slug: Page slug
            vendor_id: Vendor ID (None for defaults only)
            include_unpublished: Include draft pages

        Returns:
            ContentPage or None
        """
        ...

    def get_platform_page(
        self,
        db: "Session",
        platform_id: int,
        slug: str,
        include_unpublished: bool = False,
    ) -> object | None:
        """
        Get a platform marketing page.

        Args:
            db: Database session
            platform_id: Platform ID
            slug: Page slug
            include_unpublished: Include draft pages

        Returns:
            ContentPage or None
        """
        ...

    def list_pages_for_vendor(
        self,
        db: "Session",
        platform_id: int,
        vendor_id: int | None = None,
        include_unpublished: bool = False,
        footer_only: bool = False,
        header_only: bool = False,
        legal_only: bool = False,
    ) -> list:
        """
        List all available pages for a vendor storefront.

        Merges vendor overrides with vendor defaults, prioritizing overrides.

        Args:
            db: Database session
            platform_id: Platform ID
            vendor_id: Vendor ID (None for vendor defaults only)
            include_unpublished: Include draft pages
            footer_only: Only pages marked for footer display
            header_only: Only pages marked for header display
            legal_only: Only pages marked for legal/bottom bar display

        Returns:
            List of ContentPage objects
        """
        ...

    def list_platform_pages(
        self,
        db: "Session",
        platform_id: int,
        include_unpublished: bool = False,
        footer_only: bool = False,
        header_only: bool = False,
    ) -> list:
        """
        List platform marketing pages.

        Args:
            db: Database session
            platform_id: Platform ID
            include_unpublished: Include draft pages
            footer_only: Only pages marked for footer display
            header_only: Only pages marked for header display

        Returns:
            List of platform marketing ContentPage objects
        """
        ...


@runtime_checkable
class MediaServiceProtocol(Protocol):
    """
    Protocol for media library service.

    Defines the interface for managing media files (images, documents, etc.).
    """

    def get_media_by_id(
        self,
        db: "Session",
        media_id: int,
    ) -> object | None:
        """Get media item by ID."""
        ...

    def list_media_for_vendor(
        self,
        db: "Session",
        vendor_id: int,
        media_type: str | None = None,
    ) -> list:
        """List media items for a vendor."""
        ...