errors

type ClassifyOptions struct {
	Component  string
	Operation  string
	StatusCode int
	Context    ErrorContext
}

type ErrorCategory string

type ErrorContext struct {
	UserID     string            // User ID involved in the operation
	RequestID  string            // Request ID for tracing
	SessionID  string            // Session ID for context
	Endpoint   string            // API endpoint involved
	StatusCode int               // HTTP status code (if applicable)
	Query      string            // Database query (sanitized)
	Package    string            // Package/function where error occurred
	File       string            // File where error occurred
	Line       int               // Line number where error occurred
	Extra      map[string]string // Additional context
}

type ErrorContextOption func(*StructuredError)

type RecoverySuggestion struct {
	Action        string        // Human-readable recovery action
	Steps         []string      // Detailed recovery steps
	Documentation string        // Link to relevant documentation
	Severity      SeverityLevel // Recovery urgency
}

type RetryPolicy struct {
	MaxRetries   int           // Maximum number of retry attempts
	InitialDelay time.Duration // Initial delay before first retry
	MaxDelay     time.Duration // Maximum delay between retries
	Multiplier   float64       // Backoff multiplier (for exponential backoff)
	Strategy     RetryStrategy // Retry strategy to use
}

type RetryStrategy string

type SeverityLevel string

type StructuredError struct {
	// Core error information
	Type     ErrorCategory // Categorized error type
	Severity SeverityLevel // Error severity level
	Message  string        // Human-readable error message
	Code     string        // Machine-readable error code

	// Context information
	Component string       // Component/package where error occurred
	Operation string       // Operation being performed
	Context   ErrorContext // Additional contextual information

	// Domain-specific context fields
	CommitSHA string // Commit SHA associated with the error
	Position  int64  // Position/offset in data stream
	Email     string // Email address involved in the error
	TraceID   string // Trace ID for distributed tracing
	RecordKey string // Record key for database/storage operations

	// Technical details
	Cause      error     // Underlying error (for wrapping)
	StackTrace string    // Stack trace at error site
	Timestamp  time.Time // When the error occurred

	// Retry/Recovery information
	Retryable   bool               // Whether this error is retryable
	RetryPolicy RetryPolicy        // Retry strategy if retryable
	Recovery    RecoverySuggestion // Suggested recovery actions

	// Additional metadata
	Metadata map[string]interface{} // Additional context
}