"""Base sync service protocol for integrations.

This module defines the protocol (interface) that integration sync services
should follow. Sync services are responsible for fetching data from external
platforms and storing it in the local database.

Sync services handle:
- Incremental sync (fetching only new/updated data)
- Full sync (fetching all data)
- Cursor management for pagination
- Error handling and recovery
"""

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class BaseSyncService(Protocol):
    """Protocol defining the interface for integration sync services.

    Integration sync services should implement this protocol to ensure
    consistent behavior across different integrations.

    Note: This is a Protocol for documentation and type-checking purposes.
    Existing services (GitHubSyncService, LinkedInSyncService) don't need
    to explicitly inherit from this - they just need to implement the
    expected interface.
    """

    def sync(self, *, full_sync: bool = False) -> dict[str, Any]:
        """Execute sync operation.

        Args:
            full_sync: If True, fetch all data regardless of cursors.
                      If False, perform incremental sync from last position.

        Returns:
            Dictionary with sync results including:
            - success: bool
            - threads_synced: int (or equivalent for the integration)
            - messages_synced: int (or equivalent)
            - signals_synced: int (or equivalent)
            - errors: list[str] (any non-fatal errors encountered)

        Raises:
            IntegrationError: If sync fails fatally
        """
        ...