//! User-friendly hints for ProcessedError responses.
//!
//! Centralizes actionable hint text returned to API clients, making it easy
//! to update messaging across the codebase and keep tone consistent.

/// Hint for when a column is not found in query results.
pub const COLUMN_NOT_FOUND: &str =
    "This may indicate a mismatch between the query and expected result structure.";

/// Hint for when a requested record was not found.
pub const ROW_NOT_FOUND: &str = "Verify the identifier and try again.";

/// Hint for unique constraint violations.
pub const UNIQUE_VIOLATION: &str = "Please use a different value or update the existing record.";

/// Hint for foreign key constraint violations.
pub const FOREIGN_KEY_VIOLATION: &str = "Ensure all referenced resources exist and are accessible.";

/// Hint for not-null constraint violations.
pub const NOT_NULL_VIOLATION: &str = "Please provide all required fields.";

/// Hint for check constraint violations.
pub const CHECK_CONSTRAINT_VIOLATION: &str =
    "Please ensure the value meets all validation requirements.";

/// Hint for text encoding violations.
pub const INVALID_TEXT_ENCODING: &str =
    "Remove unsupported characters and ensure text is valid UTF-8.";

/// Hint for undefined column errors.
pub const UNDEFINED_COLUMN: &str = "Please verify the column name and try again.";

/// Hint for undefined table when the table name is known.
pub const UNDEFINED_TABLE_WITH_NAME: &str = "It may not exist yet, or you might have a typo. Check your migrations or ensure you're connected to the correct schema.";

/// Hint for undefined table when the table name is unknown.
pub const UNDEFINED_TABLE_GENERIC: &str =
    "Please verify the table name and ensure it has been created.";

/// Hint for SQL syntax errors.
pub const SYNTAX_ERROR: &str = "Please check your query syntax.";

/// Hint for incompatible text/UUID comparisons.
pub const TEXT_UUID_OPERATOR_MISMATCH: &str = "Cast both sides to the same type. For Athena gateway filters, enable gateway.auto_cast_uuid_filter_values_to_text.";

/// Hint for insufficient privilege errors.
pub const INSUFFICIENT_PRIVILEGE: &str = "Please contact an administrator for access.";

/// Hint for database connection issues.
pub const CONNECTION_ERROR: &str = "The database is temporarily unavailable. Please try again.";

/// Hint for internal/unexpected errors.
pub const INTERNAL_ERROR: &str =
    "An unexpected error occurred. Please contact support if this persists.";

/// Hint for pool timeout.
pub const POOL_TIMEOUT: &str =
    "The system is experiencing high load. Please try again in a moment.";

/// Hint for pool closed.
pub const POOL_CLOSED: &str =
    "The database connection pool has been shut down. Please contact support.";

/// Returns the message and hint for an undefined table error.
///
/// When the table name is known, uses a friendlier message; otherwise falls back
/// to the generic formulation.
pub fn undefined_table(table_name: Option<&str>) -> (String, &'static str) {
    match table_name {
        Some(t) => (
            format!("The table '{}' was not found.", t),
            UNDEFINED_TABLE_WITH_NAME,
        ),
        None => (
            "The specified table does not exist".to_string(),
            UNDEFINED_TABLE_GENERIC,
        ),
    }
}
