"""FastAPI dependency for validating recipient data."""

from typing import Annotated

from fastapi import Depends

from .types import RecipientData


async def validate_recipient_data(data: RecipientData) -> RecipientData:
    """FastAPI dependency for validating recipient data.

    Pydantic automatically validates the request body and returns 422
    for validation errors. This dependency exists for explicit clarity
    and to allow custom logic if needed in the future.

    Args:
        data: Validated RecipientData from request body (auto-validated by Pydantic)

    Returns:
        RecipientData object

    Raises:
        HTTPException: 422 if validation fails (automatic via Pydantic)

    Example:
        ```python
        from ingress_recipient import RecipientData, validate_recipient_data
        from fastapi import APIRouter, Depends

        router = APIRouter()

        @router.post("/destinations/telemetry")
        async def receive_telemetry(
            data: RecipientData = Depends(validate_recipient_data),
        ):
            # data is fully typed and validated
            print(f"Received data from channel {data.channel_id}")

            # Process data...
            await save_telemetry(data)

            return {"status": "accepted"}
        ```

        You can also use the ValidatedRecipientData type alias for cleaner code:

        ```python
        from ingress_recipient import ValidatedRecipientData

        @router.post("/destinations/telemetry")
        async def receive_telemetry(data: ValidatedRecipientData):
            # data is fully typed and validated
            print(f"Received data from channel {data.channel_id}")
            return {"status": "accepted"}
        ```
    """
    return data


# Type alias for cleaner endpoint signatures
ValidatedRecipientData = Annotated[RecipientData, Depends(validate_recipient_data)]
"""Type alias for validated recipient data in FastAPI endpoints.

This combines the RecipientData type with the validation dependency,
allowing for cleaner endpoint signatures.

Example:
    ```python
    from ingress_recipient import ValidatedRecipientData

    @router.post("/destinations/telemetry")
    async def receive_telemetry(data: ValidatedRecipientData):
        # data is automatically validated
        print(f"Channel: {data.channel_id}")
        return {"status": "accepted"}
    ```
"""
