"""Tenant resolver protocol for wl-apdp SDK.

Applications implement the TenantResolver protocol to provide
app-specific tenant and user context resolution.
"""

from __future__ import annotations

from typing import Any, Protocol


class TenantResolver(Protocol):
    """Protocol that applications implement to resolve tenant/user context.

    The APDP client calls these methods to extract app-specific
    identifiers from job data and user context.
    """

    def resolve_tenant_id(self, job_data: dict[str, Any]) -> str:
        """Extract the tenant ID from job data.

        Args:
            job_data: The full job payload.

        Returns:
            The tenant identifier (e.g., family ID, org ID).
        """
        ...

    def resolve_user_context(self, user_context: dict[str, Any]) -> dict[str, Any]:
        """Normalize user context into a standard format.

        Args:
            user_context: Raw user identity from the API gateway.

        Returns:
            Normalized user context with at least "userId", "email", "roles".
        """
        ...

    def get_idp_name(self) -> str:
        """Return the identity provider name for delegation chains.

        Returns:
            The IDP identifier (e.g., "unisyn", "okta", "auth0").
        """
        ...
