Flaro/Packages/FlixyKit/Sources/PlexKit/Models/PlexItem.swift

import Foundation

/// Ein Eintrag in der Mediathek — Film, Serie, Staffel oder Folge.
///
/// Plex verwendet für alle vier denselben Datensatz und unterscheidet über
/// `type`. Das ist ungewohnt, aber praktisch: Suchergebnisse und Reihen auf
/// der Startseite mischen die Arten, und ein gemeinsamer Typ erspart das
/// Aufteilen bei jedem Abruf.
public struct PlexItem: Sendable, Equatable, Codable, Identifiable {
    public enum Kind: String, Sendable, Codable {
        case movie, show, season, episode, clip, collection
    }

    /// Die Kennung, unter der der Server den Eintrag führt. Kommt als
    /// Zeichenkette, obwohl es eine Zahl ist.
    public let ratingKey: String
    public let key: String
    public let guid: String?
    public let type: String
    public let title: String
    public let titleSort: String?
    public let summary: String?
    public let year: Int?
    /// Laufzeit in Millisekunden.
    public let duration: Int?
    public let contentRating: String?
    public let rating: Double?
    public let audienceRating: Double?

    // Bildpfade. Relativ zum Server — die vollständige Adresse entsteht erst
    // beim Abruf, weil sie Token und Größenangaben braucht.
    public let thumb: String?
    public let art: String?
    public let parentThumb: String?
    public let grandparentThumb: String?
    public let grandparentArt: String?

    // Einordnung bei Folgen: `index` ist die Folgennummer, `parentIndex` die
    // Staffel, `grandparentTitle` der Serientitel.
    public let index: Int?
    public let parentIndex: Int?
    public let parentTitle: String?
    public let parentRatingKey: String?
    public let grandparentTitle: String?
    public let grandparentRatingKey: String?

    // Fortschritt.
    public let viewCount: Int?
    /// Wie weit gesehen wurde, in Millisekunden.
    public let viewOffset: Int?
    public let lastViewedAt: Int?
    public let addedAt: Int?

    // Zählwerte bei Serien und Staffeln.
    public let leafCount: Int?
    public let viewedLeafCount: Int?
    public let childCount: Int?

    public let media: [PlexMedia]

    private enum CodingKeys: String, CodingKey {
        case ratingKey, key, guid, type, title, titleSort, summary, year, duration
        case contentRating, rating, audienceRating
        case thumb, art, parentThumb, grandparentThumb, grandparentArt
        case index, parentIndex, parentTitle, parentRatingKey
        case grandparentTitle, grandparentRatingKey
        case viewCount, viewOffset, lastViewedAt, addedAt
        case leafCount, viewedLeafCount, childCount
        case media = "Media"
    }

    /// Von Hand geschrieben statt erzeugt, weil der erzeugte Decoder einen
    /// `Media`-Block verlangen würde. Plex liefert Einträge aber schon aus,
    /// bevor es die Dateien analysiert hat — ohne diese Nachsicht wäre eine
    /// frisch hinzugefügte Staffel als Ganzes unlesbar statt nur unvollständig.
    public init(from decoder: any Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)

        self.ratingKey = try values.decode(String.self, forKey: .ratingKey)
        self.key = try values.decodeIfPresent(String.self, forKey: .key) ?? "/library/metadata/\(ratingKey)"
        self.guid = try values.decodeIfPresent(String.self, forKey: .guid)
        self.type = try values.decode(String.self, forKey: .type)
        self.title = try values.decode(String.self, forKey: .title)
        self.titleSort = try values.decodeIfPresent(String.self, forKey: .titleSort)
        self.summary = try values.decodeIfPresent(String.self, forKey: .summary)
        self.year = try values.decodeIfPresent(Int.self, forKey: .year)
        self.duration = try values.decodeIfPresent(Int.self, forKey: .duration)
        self.contentRating = try values.decodeIfPresent(String.self, forKey: .contentRating)
        self.rating = try values.decodeIfPresent(Double.self, forKey: .rating)
        self.audienceRating = try values.decodeIfPresent(Double.self, forKey: .audienceRating)

        self.thumb = try values.decodeIfPresent(String.self, forKey: .thumb)
        self.art = try values.decodeIfPresent(String.self, forKey: .art)
        self.parentThumb = try values.decodeIfPresent(String.self, forKey: .parentThumb)
        self.grandparentThumb = try values.decodeIfPresent(String.self, forKey: .grandparentThumb)
        self.grandparentArt = try values.decodeIfPresent(String.self, forKey: .grandparentArt)

        self.index = try values.decodeIfPresent(Int.self, forKey: .index)
        self.parentIndex = try values.decodeIfPresent(Int.self, forKey: .parentIndex)
        self.parentTitle = try values.decodeIfPresent(String.self, forKey: .parentTitle)
        self.parentRatingKey = try values.decodeIfPresent(String.self, forKey: .parentRatingKey)
        self.grandparentTitle = try values.decodeIfPresent(String.self, forKey: .grandparentTitle)
        self.grandparentRatingKey = try values.decodeIfPresent(String.self, forKey: .grandparentRatingKey)

        self.viewCount = try values.decodeIfPresent(Int.self, forKey: .viewCount)
        self.viewOffset = try values.decodeIfPresent(Int.self, forKey: .viewOffset)
        self.lastViewedAt = try values.decodeIfPresent(Int.self, forKey: .lastViewedAt)
        self.addedAt = try values.decodeIfPresent(Int.self, forKey: .addedAt)

        self.leafCount = try values.decodeIfPresent(Int.self, forKey: .leafCount)
        self.viewedLeafCount = try values.decodeIfPresent(Int.self, forKey: .viewedLeafCount)
        self.childCount = try values.decodeIfPresent(Int.self, forKey: .childCount)

        self.media = try values.decodeIfPresent([PlexMedia].self, forKey: .media) ?? []
    }

    /// `ratingKey` ist serverweit eindeutig und eignet sich deshalb direkt
    /// als Kennung für `ForEach`.
    public var id: String { ratingKey }

    public var kind: Kind? { Kind(rawValue: type) }

    /// Wie weit der Titel gesehen ist, als Anteil von 0 bis 1.
    ///
    /// `nil`, wenn noch gar nicht angefangen wurde — die Kachel zeigt dann
    /// keinen Balken statt eines leeren.
    public var watchProgress: Double? {
        guard let viewOffset, let duration, duration > 0, viewOffset > 0 else { return nil }
        return min(Double(viewOffset) / Double(duration), 1)
    }

    public var isWatched: Bool { (viewCount ?? 0) > 0 }

    /// Die Fassung, die abgespielt werden soll, wenn der Nutzer nichts anderes
    /// wählt: die mit der höchsten Bitrate. Plex sortiert nicht zuverlässig,
    /// deshalb wird hier selbst ausgewählt.
    public var preferredMedia: PlexMedia? {
        media.max { ($0.bitrate ?? 0) < ($1.bitrate ?? 0) }
    }

    /// Ob die Detailseite eine Versionsauswahl anbieten muss.
    public var hasMultipleVersions: Bool { media.count > 1 }
}

/// Die Hülle, in die Plex jede Antwort packt.
///
/// Der Name des Inhaltsfelds wechselt je nach Endpunkt (`Metadata`,
/// `Directory`, `Hub`), die Hülle selbst bleibt gleich. Deshalb ist sie
/// generisch über den Inhalt.
public struct PlexMediaContainer<Content: Decodable & Sendable>: Sendable, Decodable {
    public let size: Int?
    /// Wie viele Einträge es insgesamt gibt — wichtig fürs seitenweise
    /// Nachladen, weil `size` nur die aktuelle Seite zählt.
    public let totalSize: Int?
    public let offset: Int?
    public let title1: String?
    public let title2: String?
    public let content: [Content]

    private enum OuterKeys: String, CodingKey { case mediaContainer = "MediaContainer" }
    private enum InnerKeys: String, CodingKey {
        case size, totalSize, offset, title1, title2
        case metadata = "Metadata"
        case directory = "Directory"
    }

    public init(from decoder: any Decoder) throws {
        let outer = try decoder.container(keyedBy: OuterKeys.self)
        let inner = try outer.nestedContainer(keyedBy: InnerKeys.self, forKey: .mediaContainer)

        self.size = try inner.decodeIfPresent(Int.self, forKey: .size)
        self.totalSize = try inner.decodeIfPresent(Int.self, forKey: .totalSize)
        self.offset = try inner.decodeIfPresent(Int.self, forKey: .offset)
        self.title1 = try inner.decodeIfPresent(String.self, forKey: .title1)
        self.title2 = try inner.decodeIfPresent(String.self, forKey: .title2)

        // `Metadata` bei Titeln, `Directory` bei Bibliotheken und Staffeln.
        // Eine leere Mediathek liefert gar kein Feld — das ist kein Fehler,
        // sondern bedeutet schlicht null Einträge.
        if let metadata = try inner.decodeIfPresent([Content].self, forKey: .metadata) {
            self.content = metadata
        } else if let directory = try inner.decodeIfPresent([Content].self, forKey: .directory) {
            self.content = directory
        } else {
            self.content = []
        }
    }
}