luminate/Sources/LuminateCore/Models/JellyfinMediaItem.swift

//
//  JellyfinMediaItem.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 Foundation

/// A movie, series, season, or episode as Luminate renders it.
///
/// This is the domain counterpart of the server's `BaseItemDto`, which carries well over a hundred
/// fields. Most properties are `nil` unless the originating query requested the matching
/// ``JellyfinItemField``, so a list query and a detail query return the same type at different
/// levels of detail.
package struct JellyfinMediaItem: Hashable, Sendable {
    /// The server-assigned item identifier.
    package var id: String?
    /// The display title.
    package var name: String?
    /// The title in the original production language.
    package var originalTitle: String?
    /// The identifier of the server holding the item.
    package var serverID: String?
    /// What kind of item this is; `nil` when the server reported a kind Luminate does not model.
    package var kind: JellyfinMediaKind?
    /// The library type, set only on library folders.
    package var collectionType: JellyfinCollectionType?
    /// The long-form synopsis.
    package var overview: String?
    /// Marketing taglines.
    package var taglines: [String]?
    /// The genres attached to the item.
    package var genres: [String]?
    /// The parental rating certificate, such as `PG-13`.
    package var officialRating: String?
    /// The aggregate community score, out of ten.
    package var communityRating: Float?
    /// The aggregate critic score, out of one hundred.
    package var criticRating: Float?
    /// The year of production.
    package var productionYear: Int32?
    /// The original release date.
    package var premiereDate: Date?
    /// When the item was added to the library.
    package var dateCreated: Date?
    /// The total duration, in 100-nanosecond ticks.
    package var runTimeTicks: Int64?
    /// The episode number within its season, or the season number for a season.
    package var indexNumber: Int32?
    /// The season number, for episodes.
    package var parentIndexNumber: Int32?
    /// The identifier of the containing item.
    package var parentID: String?
    /// The title of the parent series, for seasons and episodes.
    package var seriesName: String?
    /// The identifier of the parent series, for seasons and episodes.
    package var seriesID: String?
    /// The identifier of the parent season, for episodes.
    package var seasonID: String?
    /// The title of the parent season, for episodes.
    package var seasonName: String?
    /// How many direct children the item has.
    package var childCount: Int32?
    /// The video width in pixels.
    package var width: Int32?
    /// The video height in pixels.
    package var height: Int32?
    /// The aspect ratio of the primary image, useful for sizing a poster before it loads.
    package var primaryImageAspectRatio: Double?
    /// The artwork slots this item has, keyed by type; the values are cache-busting image tags.
    ///
    /// Slots the server reported under a type Luminate does not model are dropped.
    package var imageTags: [JellyfinImageType: String]
    /// The tags of the item's backdrop images, in server order.
    package var backdropImageTags: [String]
    /// The requesting user's playback and favourite state, when the query enabled user data.
    package var userData: JellyfinUserData?

    /// Creates a media item, defaulting every unspecified field to `nil` or empty.
    ///
    /// Each parameter sets the property of the same name.
    package init(
        id: String? = nil,
        name: String? = nil,
        originalTitle: String? = nil,
        serverID: String? = nil,
        kind: JellyfinMediaKind? = nil,
        collectionType: JellyfinCollectionType? = nil,
        overview: String? = nil,
        taglines: [String]? = nil,
        genres: [String]? = nil,
        officialRating: String? = nil,
        communityRating: Float? = nil,
        criticRating: Float? = nil,
        productionYear: Int32? = nil,
        premiereDate: Date? = nil,
        dateCreated: Date? = nil,
        runTimeTicks: Int64? = nil,
        indexNumber: Int32? = nil,
        parentIndexNumber: Int32? = nil,
        parentID: String? = nil,
        seriesName: String? = nil,
        seriesID: String? = nil,
        seasonID: String? = nil,
        seasonName: String? = nil,
        childCount: Int32? = nil,
        width: Int32? = nil,
        height: Int32? = nil,
        primaryImageAspectRatio: Double? = nil,
        imageTags: [JellyfinImageType: String] = [:],
        backdropImageTags: [String] = [],
        userData: JellyfinUserData? = nil
    ) {
        self.id = id
        self.name = name
        self.originalTitle = originalTitle
        self.serverID = serverID
        self.kind = kind
        self.collectionType = collectionType
        self.overview = overview
        self.taglines = taglines
        self.genres = genres
        self.officialRating = officialRating
        self.communityRating = communityRating
        self.criticRating = criticRating
        self.productionYear = productionYear
        self.premiereDate = premiereDate
        self.dateCreated = dateCreated
        self.runTimeTicks = runTimeTicks
        self.indexNumber = indexNumber
        self.parentIndexNumber = parentIndexNumber
        self.parentID = parentID
        self.seriesName = seriesName
        self.seriesID = seriesID
        self.seasonID = seasonID
        self.seasonName = seasonName
        self.childCount = childCount
        self.width = width
        self.height = height
        self.primaryImageAspectRatio = primaryImageAspectRatio
        self.imageTags = imageTags
        self.backdropImageTags = backdropImageTags
        self.userData = userData
    }
}