# Copyright (c) CloudZero - ALL RIGHTS RESERVED - PROPRIETARY AND CONFIDENTIAL
# Unauthorized copying of this file and/or project, via any medium is strictly prohibited.
# Direct all questions to legal@cloudzero.com
#

"""
Standardized V4 Error Response Models

This module provides standardized Pydantic models for V4 API error responses
to ensure consistent error handling across all API clients.
"""

from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field


class V4ErrorResponse(BaseModel):
    """
    Standardized V4 API error response model.

    All V4 API endpoints return errors in this consistent format with
    structured JSON including error codes and timestamps.
    """

    error: str = Field(..., description="Human-readable error description")
    details: str = Field(..., description="Additional technical details or context")
    error_code: str | None = Field(None, description="Machine-readable error code (optional)")
    timestamp: str = Field(..., description="ISO 8601 timestamp with microsecond precision")

    model_config = ConfigDict(extra="allow")


# Standard V4 API error codes for programmatic handling
class V4ErrorCodes:
    """Standard error codes used across V4 APIs."""

    # System-Level Error Codes
    INTERNAL_ERROR = "INTERNAL_ERROR"
    INVALID_REQUEST = "INVALID_REQUEST"

    # Authentication & Authorization
    MISSING_AUTH_CONTEXT = "MISSING_AUTH_CONTEXT"
    INVALID_TOKEN = "INVALID_TOKEN"  # noqa: S105 - Not a password, just an error code

    # Validation Errors
    VALIDATION_ERROR = "VALIDATION_ERROR"
    MISSING_REQUEST_BODY = "MISSING_REQUEST_BODY"
    INVALID_ORGANIZATION_ID = "INVALID_ORGANIZATION_ID"
    MISSING_USER_ID = "MISSING_USER_ID"

    # Resource Errors
    CONNECTION_NOT_FOUND = "CONNECTION_NOT_FOUND"
    ORGANIZATION_NOT_FOUND = "ORGANIZATION_NOT_FOUND"
    DOCUMENT_NOT_FOUND = "DOCUMENT_NOT_FOUND"
    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"

    # Service-Specific Errors
    QUICKSIGHT_DASHBOARDS_ERROR = "QUICKSIGHT_DASHBOARDS_ERROR"
    QUICKSIGHT_FOLDER_ERROR = "QUICKSIGHT_FOLDER_ERROR"
    QUICKSIGHT_SPICE_ERROR = "QUICKSIGHT_SPICE_ERROR"
    QUICKSIGHT_UPDATE_ERROR = "QUICKSIGHT_UPDATE_ERROR"
    RESOURCE_QUERY_ERROR = "RESOURCE_QUERY_ERROR"
    UPDATE_FAILED = "UPDATE_FAILED"
    NO_UPDATE_FIELDS = "NO_UPDATE_FIELDS"

    # Auto-link Specific
    AUTOLINK_CONFIG_ERROR = "AUTOLINK_CONFIG_ERROR"
    AUTOLINK_STATUS_ERROR = "AUTOLINK_STATUS_ERROR"

    # System Operations
    CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED"


def create_v4_error_response(
    error: str, details: str, error_code: str | None = None, timestamp: str | None = None
) -> V4ErrorResponse:
    """
    Create a standardized V4 error response.

    Args:
        error: Human-readable error message
        details: Additional technical details or context
        error_code: Machine-readable error code
        timestamp: Optional ISO 8601 timestamp (will generate current time if None)

    Returns:
        V4ErrorResponse: Standardized error response
    """
    if timestamp is None:
        timestamp = datetime.utcnow().isoformat(timespec="microseconds") + "Z"

    return V4ErrorResponse(error=error, details=details, error_code=error_code, timestamp=timestamp)


def is_v4_error_response(response_data: dict) -> bool:
    """
    Check if a response dictionary is a V4 error response.

    Args:
        response_data: API response data dictionary

    Returns:
        bool: True if response is a V4 error format
    """
    required_fields = {"error", "details", "timestamp"}
    return all(field in response_data for field in required_fields)
