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

/// Shared options for the narrow list endpoints -- libraries, resume, next up, latest, seasons,
/// episodes, and search.
///
/// Those endpoints each accept a small, overlapping set of knobs, and a protocol requirement cannot
/// declare default arguments. Collapsing them into one bag keeps ``JellyfinService`` readable and
/// lets call sites set only what they care about. Not every option applies to every endpoint; an
/// option an endpoint has no parameter for is ignored.
///
/// ```swift
/// let upNext = try await client.nextUp(options: JellyfinListOptions(userID: userID, limit: 20))
/// ```
package struct JellyfinListOptions: Hashable, Sendable {
    /// Restrict results to what this user may see, and populate their playback state.
    package var userID: String?
    /// Restrict results to descendants of this item, normally a library.
    package var parentID: String?
    /// Restrict results to this season, for the episode listing.
    package var seasonID: String?
    /// Restrict results to this season number, for the episode listing.
    package var season: Int32?
    /// Skip this many matching items before the first result.
    package var startIndex: Int32?
    /// Return at most this many items.
    package var limit: Int32?
    /// Optional metadata to populate on each returned item.
    package var fields: [JellyfinItemField]?
    /// Only return these kinds of item, where the endpoint supports filtering by kind.
    package var includeItemKinds: [JellyfinMediaKind]?
    /// Include libraries the server hides from the home screen, for the library listing.
    package var includeHidden: Bool?
    /// Collapse episodes of the same series into one entry, for the latest-media listing.
    package var groupItems: Bool?

    /// Creates an empty option set, leaving every parameter to the server's default.
    ///
    /// Each parameter sets the property of the same name.
    package init(
        userID: String? = nil,
        parentID: String? = nil,
        seasonID: String? = nil,
        season: Int32? = nil,
        startIndex: Int32? = nil,
        limit: Int32? = nil,
        fields: [JellyfinItemField]? = nil,
        includeItemKinds: [JellyfinMediaKind]? = nil,
        includeHidden: Bool? = nil,
        groupItems: Bool? = nil
    ) {
        self.userID = userID
        self.parentID = parentID
        self.seasonID = seasonID
        self.season = season
        self.startIndex = startIndex
        self.limit = limit
        self.fields = fields
        self.includeItemKinds = includeItemKinds
        self.includeHidden = includeHidden
        self.groupItems = groupItems
    }
}