//
//  JellyfinClientError.swift
//
//  Copyright 2026 Brendan Szymanski <hello@bscubed.dev>
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
//  SPDX-License-Identifier: GPL-3.0-or-later
//

/// A failure Luminate's Jellyfin service layer raises on its own behalf.
///
/// This covers argument validation, the HTTP statuses the Jellyfin API documents, and responses
/// that arrive without the payload the spec promises. Transport failures, decoding failures, and
/// oversized response bodies are *not* wrapped: those propagate from the OpenAPI runtime unchanged
/// so their diagnostics survive.
package enum JellyfinClientError: Error, Hashable, Sendable {
    /// No server has been configured for this service.
    ///
    /// Thrown by the placeholder service that fills the `\.client` environment slot when nothing
    /// was injected, so a missing `.environment(\.client, ...)` fails loudly at the first call
    /// instead of quietly talking to the wrong host.
    case notConfigured
    /// A required argument was empty or otherwise unusable, so no request was sent.
    ///
    /// - Parameter name: The Swift parameter name that was rejected.
    case invalidArgument(name: String)
    /// The server rejected the credentials, or the access token expired. Sign in again.
    case unauthorized
    /// The account is authenticated but not permitted to perform the operation.
    case forbidden
    /// The requested item, image, or user does not exist on the server.
    case notFound
    /// The server rejected the request as malformed.
    case badRequest
    /// The server is starting up or otherwise temporarily unavailable.
    ///
    /// - Parameter retryAfterSeconds: How long the server asked the client to wait, when it said.
    case serviceUnavailable(retryAfterSeconds: Int32?)
    /// The server answered with a status the API specification does not document.
    ///
    /// - Parameters:
    ///   - operation: The Jellyfin operation identifier, such as `GetItems`.
    ///   - statusCode: The HTTP status code received.
    case unexpectedStatus(operation: String, statusCode: Int)
    /// The server answered successfully but omitted a value the operation cannot proceed without.
    ///
    /// - Parameter operation: The Jellyfin operation identifier, such as `AuthenticateUserByName`.
    case missingPayload(operation: String)
}