//
//  JellyfinAPI.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
//

import LuminateAPI

/// The slice of the generated Jellyfin API that ``JellyfinClient`` actually calls.
///
/// The seam exists so a test double conforms to a protocol this module owns rather than to the
/// generated `APIProtocol`, whose shape is decided by
/// `Sources/LuminateAPI/openapi-generator-config.yaml`. Adding an operation here also requires
/// adding its `operationId` to that file's `filter.operations` list, or the generated `Client`
/// will not have the method. The generated `Client` already has matching signatures, so it
/// conforms with an empty extension.
///
/// This is a service-layer seam and nothing more: it deals in generated `Operations.*` types, which
/// never travel above ``JellyfinClient``.
package protocol JellyfinAPI: Sendable {
    /// Signs in with a username and password.
    ///
    /// - Parameter input: The generated `AuthenticateUserByName` input.
    /// - Returns: The generated `AuthenticateUserByName` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func authenticateUserByName(_ input: Operations.AuthenticateUserByName.Input) async throws
        -> Operations.AuthenticateUserByName.Output

    /// Redeems an approved Quick Connect secret for an access token.
    ///
    /// - Parameter input: The generated `AuthenticateWithQuickConnect` input.
    /// - Returns: The generated `AuthenticateWithQuickConnect` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func authenticateWithQuickConnect(_ input: Operations.AuthenticateWithQuickConnect.Input) async throws
        -> Operations.AuthenticateWithQuickConnect.Output

    /// Lists the accounts a server advertises before sign-in.
    ///
    /// - Parameter input: The generated `GetPublicUsers` input.
    /// - Returns: The generated `GetPublicUsers` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getPublicUsers(_ input: Operations.GetPublicUsers.Input) async throws -> Operations.GetPublicUsers.Output

    /// Reads the server information available without authentication.
    ///
    /// - Parameter input: The generated `GetPublicSystemInfo` input.
    /// - Returns: The generated `GetPublicSystemInfo` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getPublicSystemInfo(_ input: Operations.GetPublicSystemInfo.Input) async throws
        -> Operations.GetPublicSystemInfo.Output

    /// Reads the full server information.
    ///
    /// - Parameter input: The generated `GetSystemInfo` input.
    /// - Returns: The generated `GetSystemInfo` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getSystemInfo(_ input: Operations.GetSystemInfo.Input) async throws -> Operations.GetSystemInfo.Output

    /// Reports whether the server allows Quick Connect pairing.
    ///
    /// - Parameter input: The generated `GetQuickConnectEnabled` input.
    /// - Returns: The generated `GetQuickConnectEnabled` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getQuickConnectEnabled(_ input: Operations.GetQuickConnectEnabled.Input) async throws
        -> Operations.GetQuickConnectEnabled.Output

    /// Starts a Quick Connect pairing attempt.
    ///
    /// - Parameter input: The generated `InitiateQuickConnect` input.
    /// - Returns: The generated `InitiateQuickConnect` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func initiateQuickConnect(_ input: Operations.InitiateQuickConnect.Input) async throws
        -> Operations.InitiateQuickConnect.Output

    /// Polls an in-flight Quick Connect request.
    ///
    /// - Parameter input: The generated `GetQuickConnectState` input.
    /// - Returns: The generated `GetQuickConnectState` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getQuickConnectState(_ input: Operations.GetQuickConnectState.Input) async throws
        -> Operations.GetQuickConnectState.Output

    /// Changes or resets an account password.
    ///
    /// - Parameter input: The generated `UpdateUserPassword` input.
    /// - Returns: The generated `UpdateUserPassword` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func updateUserPassword(_ input: Operations.UpdateUserPassword.Input) async throws
        -> Operations.UpdateUserPassword.Output

    /// Lists the libraries a user can browse.
    ///
    /// - Parameter input: The generated `GetUserViews` input.
    /// - Returns: The generated `GetUserViews` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getUserViews(_ input: Operations.GetUserViews.Input) async throws -> Operations.GetUserViews.Output

    /// Runs a browse, filter, or search query.
    ///
    /// - Parameter input: The generated `GetItems` input.
    /// - Returns: The generated `GetItems` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getItems(_ input: Operations.GetItems.Input) async throws -> Operations.GetItems.Output

    /// Reads one item in full detail.
    ///
    /// - Parameter input: The generated `GetItem` input.
    /// - Returns: The generated `GetItem` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getItem(_ input: Operations.GetItem.Input) async throws -> Operations.GetItem.Output

    /// Lists partially played items for the Continue Watching row.
    ///
    /// - Parameter input: The generated `GetResumeItems` input.
    /// - Returns: The generated `GetResumeItems` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getResumeItems(_ input: Operations.GetResumeItems.Input) async throws -> Operations.GetResumeItems.Output

    /// Lists the next unwatched episode of each in-progress series.
    ///
    /// - Parameter input: The generated `GetNextUp` input.
    /// - Returns: The generated `GetNextUp` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getNextUp(_ input: Operations.GetNextUp.Input) async throws -> Operations.GetNextUp.Output

    /// Lists the most recently added items.
    ///
    /// - Parameter input: The generated `GetLatestMedia` input.
    /// - Returns: The generated `GetLatestMedia` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getLatestMedia(_ input: Operations.GetLatestMedia.Input) async throws -> Operations.GetLatestMedia.Output

    /// Lists the seasons of a series.
    ///
    /// - Parameter input: The generated `GetSeasons` input.
    /// - Returns: The generated `GetSeasons` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getSeasons(_ input: Operations.GetSeasons.Input) async throws -> Operations.GetSeasons.Output

    /// Lists the episodes of a series.
    ///
    /// - Parameter input: The generated `GetEpisodes` input.
    /// - Returns: The generated `GetEpisodes` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getEpisodes(_ input: Operations.GetEpisodes.Input) async throws -> Operations.GetEpisodes.Output

    /// Runs a search-as-you-type query.
    ///
    /// - Parameter input: The generated `GetSearchHints` input.
    /// - Returns: The generated `GetSearchHints` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getSearchHints(_ input: Operations.GetSearchHints.Input) async throws -> Operations.GetSearchHints.Output

    /// Downloads the first image of a given type for an item.
    ///
    /// - Parameter input: The generated `GetItemImage` input.
    /// - Returns: The generated `GetItemImage` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getItemImage(_ input: Operations.GetItemImage.Input) async throws -> Operations.GetItemImage.Output

    /// Downloads a specific image of a given type for an item.
    ///
    /// - Parameter input: The generated `GetItemImageByIndex` input.
    /// - Returns: The generated `GetItemImageByIndex` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func getItemImageByIndex(_ input: Operations.GetItemImageByIndex.Input) async throws
        -> Operations.GetItemImageByIndex.Output

    /// Marks an item watched.
    ///
    /// - Parameter input: The generated `MarkPlayedItem` input.
    /// - Returns: The generated `MarkPlayedItem` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func markPlayedItem(_ input: Operations.MarkPlayedItem.Input) async throws -> Operations.MarkPlayedItem.Output

    /// Marks an item unwatched.
    ///
    /// - Parameter input: The generated `MarkUnplayedItem` input.
    /// - Returns: The generated `MarkUnplayedItem` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func markUnplayedItem(_ input: Operations.MarkUnplayedItem.Input) async throws -> Operations.MarkUnplayedItem.Output

    /// Adds an item to a user's favourites.
    ///
    /// - Parameter input: The generated `MarkFavoriteItem` input.
    /// - Returns: The generated `MarkFavoriteItem` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func markFavoriteItem(_ input: Operations.MarkFavoriteItem.Input) async throws -> Operations.MarkFavoriteItem.Output

    /// Removes an item from a user's favourites.
    ///
    /// - Parameter input: The generated `UnmarkFavoriteItem` input.
    /// - Returns: The generated `UnmarkFavoriteItem` output, including every documented HTTP status.
    /// - Throws: A transport or decoding error; documented HTTP statuses arrive as output cases.
    func unmarkFavoriteItem(_ input: Operations.UnmarkFavoriteItem.Input) async throws
        -> Operations.UnmarkFavoriteItem.Output
}

/// The generated client already implements every operation with a matching signature.
extension Client: JellyfinAPI {}