from datetime import datetime, timezone
from typing import Optional, Union


def normalize_timestamp(value: Union[str, int, None]) -> Optional[str]:
    """
    Normalize a timestamp value to ISO 8601 format.

    Accepts either an ISO 8601 string or a Unix timestamp (seconds) and returns
    the value as an ISO 8601 formatted string. This is useful for normalizing
    date filter parameters (from_created_at, to_created_at, etc.) before sending
    to the API.

    Args:
        value (str | int | None): The timestamp value to normalize. Can be:
            - None: Returns None
            - int: Unix timestamp in seconds, converted to ISO 8601
            - str: Assumed to be ISO 8601 format, returned as-is

    Returns:
        Optional[str]: The normalized ISO 8601 timestamp string, or None if input is None.

    Examples:
        >>> normalize_timestamp(1704067200)
        '2024-01-01T00:00:00+00:00'
        >>> normalize_timestamp('2024-01-01T00:00:00Z')
        '2024-01-01T00:00:00Z'
        >>> normalize_timestamp(None)
        None
    """
    if value is None:
        return None
    if isinstance(value, int):
        return datetime.fromtimestamp(value, tz=timezone.utc).isoformat()
    return value
