# app/modules/contracts/__init__.py
"""
Cross-module contracts using Protocol pattern.

This module defines type-safe interfaces for cross-module communication.
Modules depend on protocols rather than concrete implementations, enabling:
- Loose coupling between modules
- Testability through mock implementations
- Clear dependency boundaries

Usage:
    from app.modules.contracts.cms import ContentServiceProtocol

    class OrderService:
        def __init__(self, content: ContentServiceProtocol | None = None):
            self._content = content

        @property
        def content(self) -> ContentServiceProtocol:
            if self._content is None:
                from app.modules.cms.services import content_page_service
                self._content = content_page_service
            return self._content

Metrics Provider Pattern:
    from app.modules.contracts.metrics import MetricsProviderProtocol, MetricValue

    class OrderMetricsProvider:
        @property
        def metrics_category(self) -> str:
            return "orders"

        def get_store_metrics(self, db, store_id, context=None) -> list[MetricValue]:
            return [MetricValue(key="orders.total", value=42, label="Total", category="orders")]

Widget Provider Pattern:
    from app.modules.contracts.widgets import DashboardWidgetProviderProtocol, DashboardWidget

    class OrderWidgetProvider:
        @property
        def widgets_category(self) -> str:
            return "orders"

        def get_store_widgets(self, db, store_id, context=None) -> list[DashboardWidget]:
            return [DashboardWidget(key="orders.recent", widget_type="list", ...)]
"""

from app.modules.contracts.audit import (
    AuditEvent,
    AuditProviderProtocol,
)
from app.modules.contracts.base import ServiceProtocol
from app.modules.contracts.cms import ContentServiceProtocol, MediaUsageProviderProtocol
from app.modules.contracts.features import (
    FeatureDeclaration,
    FeatureProviderProtocol,
    FeatureScope,
    FeatureType,
    FeatureUsage,
)
from app.modules.contracts.metrics import (
    MetricsContext,
    MetricsProviderProtocol,
    MetricValue,
)
from app.modules.contracts.widgets import (
    BreakdownWidget,
    DashboardWidget,
    DashboardWidgetProviderProtocol,
    ListWidget,
    WidgetBreakdownItem,
    WidgetContext,
    WidgetListItem,
)

__all__ = [
    # Base protocols
    "ServiceProtocol",
    # CMS protocols
    "ContentServiceProtocol",
    "MediaUsageProviderProtocol",
    # Audit protocols
    "AuditEvent",
    "AuditProviderProtocol",
    # Feature protocols
    "FeatureType",
    "FeatureScope",
    "FeatureDeclaration",
    "FeatureUsage",
    "FeatureProviderProtocol",
    # Metrics protocols
    "MetricValue",
    "MetricsContext",
    "MetricsProviderProtocol",
    # Widget protocols
    "WidgetContext",
    "WidgetListItem",
    "WidgetBreakdownItem",
    "ListWidget",
    "BreakdownWidget",
    "DashboardWidget",
    "DashboardWidgetProviderProtocol",
]