"""Base API client protocol for integrations.

This module defines the protocol (interface) that integration API clients
should follow. While not strictly enforced via inheritance, clients should
implement these patterns for consistency.

API clients handle:
- Authentication (OAuth tokens, API keys, etc.)
- Request/response handling
- Rate limiting
- Error handling and retries
"""

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class BaseAPIClient(Protocol):
    """Protocol defining the interface for integration API clients.

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

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

    def _make_api_request(
        self,
        *,
        method: str,
        endpoint: str,
        params: dict[str, Any] | None = None,
        json_data: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Make an authenticated API request.

        Args:
            method: HTTP method (GET, POST, PUT, DELETE, etc.)
            endpoint: API endpoint path (without base URL)
            params: Optional query parameters
            json_data: Optional JSON body data

        Returns:
            Parsed JSON response

        Raises:
            IntegrationError: If the request fails
        """
        ...