Add API Version to JellyfinClient (#45)

* JellyfinClient.sdkGeneratedVersion & JellyfinClient.sdkMinimumVersion

* Move to generation

* add JellyfinClient.Version

* make Version properties public

---------

Co-authored-by: Ethan Pippin <[email protected]>

Author: JPKribs

Makefile

@@ -16,7 +16,7 @@ generate:
 .PHONY: update-unstable
 update-unstable: download-unstable generate
 
-# Donload the latest Jellyfin unstable spec
+# Download the latest Jellyfin unstable spec
 .PHONY: download-unstable
 download-unstable:
-	curl -fsSL https://repo.jellyfin.org/releases/openapi/jellyfin-openapi-unstable.json -o Sources/jellyfin-openapi-stable.json
+	curl -fsSL https://repo.jellyfin.org/releases/openapi/jellyfin-openapi-unstable.json -o Sources/jellyfin-openapi-stable.json

Plugins/CreateAPI/GeneratePlugin.swift

@@ -9,6 +9,9 @@
 import Foundation
 import PackagePlugin
 
+// Declared to build
+public struct JellyfinClient {}
+
 @main
 struct Plugin: CommandPlugin {
 
@@ -27,6 +30,9 @@ struct Plugin: CommandPlugin {
         // Move patch files
         try await addTaskTriggerType(context: context)
 
+        // Create the version SDK
+        try await generateVersionFile(context: context)
+
         try await lint(context: context)
 
         try await deletePatchedSchema(context: context)
@@ -134,7 +140,7 @@ struct Plugin: CommandPlugin {
             .directory
             .appending(["Sources", "Entities", "RemoteSearchResult.swift"])
 
-        let contents = try String(contentsOfFile: filePath.string)
+        let contents = try String(contentsOfFile: filePath.string, encoding: .utf8)
         var lines = contents
             .split(separator: "\n")
             .map { String($0) }
@@ -154,7 +160,7 @@ struct Plugin: CommandPlugin {
             .directory
             .appending(["Sources", "Extensions", "AnyJSON.swift"])
 
-        let contents = try String(contentsOfFile: filePath.string)
+        let contents = try String(contentsOfFile: filePath.string, encoding: .utf8)
         var lines = contents
             .split(separator: "\n")
             .map { String($0) }
@@ -195,11 +201,39 @@ struct Plugin: CommandPlugin {
             .directory
             .appending(["Sources", "Entities", "GroupUpdate.swift"])
 
-        let contents = try String(contentsOfFile: filePath.string)
+        let contents = try String(contentsOfFile: filePath.string, encoding: .utf8)
             .replacingOccurrences(of: "Type", with: "_Type")
 
         try contents
             .data(using: .utf8)?
             .write(to: URL(fileURLWithPath: filePath.string))
     }
+
+    // TODO: Remove if/when fixed within CreateAPI
+    // Adds JellyfinClient.sdkVersion
+    private func generateVersionFile(context: PluginContext) async throws {
+        let schema = try await parseOriginalSchema(context: context)
+
+        guard case let .object(file) = schema else { return }
+        guard case let .object(info) = file["info"] else { return }
+        guard let version = info["version"]?.value as? String else { return }
+
+        let sourceFilePath = context
+            .package
+            .directory
+            .appending(["Plugins", "CreateAPI", "PatchFiles", "JellyfinClient+Version.swift"])
+
+        var contents = try String(contentsOfFile: sourceFilePath.string, encoding: .utf8)
+
+        contents.replace(#/<SDK_VERSION>/#, with: version)
+
+        let destinationFilePath = context
+            .package
+            .directory
+            .appending(["Sources", "Extensions", "JellyfinClient+Version.swift"])
+
+        try contents
+            .data(using: .utf8)?
+            .write(to: URL(fileURLWithPath: destinationFilePath.string))
+    }
 }

Plugins/CreateAPI/PatchFiles/JellyfinClient+Version.swift

@@ -0,0 +1,78 @@
+//
+// jellyfin-sdk-swift is subject to the terms of the Mozilla Public
+// License, v2.0. If a copy of the MPL was not distributed with this
+// file, you can obtain one at https://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) 2025 Jellyfin & Jellyfin Contributors
+//
+
+public extension JellyfinClient {
+    /// Version of Jellyfin used to generate the SDK
+    static let sdkVersion: Version = "<SDK_VERSION>"
+}
+
+public extension JellyfinClient {
+
+    struct Version: Comparable, CustomStringConvertible, ExpressibleByStringLiteral {
+
+        public let major: Int
+        public let minor: Int
+        public let patch: Int
+
+        public var description: String {
+            "\(major).\(minor).\(patch)"
+        }
+
+        public var majorMinor: Version {
+            Version(major: major, minor: minor, patch: 0)
+        }
+
+        public init(stringLiteral value: StringLiteralType) {
+            let parsed = Version.parse(value: value)
+            self.major = parsed.major
+            self.minor = parsed.minor
+            self.patch = parsed.patch
+        }
+
+        public init(major: Int, minor: Int, patch: Int) {
+            self.major = max(0, major)
+            self.minor = max(0, minor)
+            self.patch = max(0, patch)
+        }
+
+        private static func parse(value: String) -> (major: Int, minor: Int, patch: Int) {
+            let components = value.split(separator: ".")
+
+            guard components.count == 3 else {
+                return (0, 0, 0)
+            }
+
+            guard let major = Int(components[0]),
+                  let minor = Int(components[1]),
+                  let patch = Int(components[2])
+            else {
+                return (0, 0, 0)
+            }
+
+            guard major >= 0 && minor >= 0 && patch >= 0 else {
+                return (0, 0, 0)
+            }
+
+            return (major, minor, patch)
+        }
+
+        public static func == (lhs: Version, rhs: Version) -> Bool {
+            lhs.major == rhs.major && lhs.minor == rhs.minor && lhs.patch == rhs.patch
+        }
+
+        public static func < (lhs: Version, rhs: Version) -> Bool {
+            if lhs.major != rhs.major {
+                return lhs.major < rhs.major
+            }
+            if lhs.minor != rhs.minor {
+                return lhs.minor < rhs.minor
+            }
+            return lhs.patch < rhs.patch
+        }
+    }
+}

Sources/Entities/BaseItemDto.swift

@@ -154,7 +154,7 @@ public struct BaseItemDto: Codable, Hashable, Identifiable {
     public var mediaSources: [MediaSourceInfo]?
     /// Gets or sets the media streams.
     public var mediaStreams: [MediaStream]?
-    /// Media types.
+    /// Gets or sets the type of the media.
     public var mediaType: MediaType?
     /// Gets or sets the movie count.
     public var movieCount: Int?
@@ -273,7 +273,7 @@ public struct BaseItemDto: Codable, Hashable, Identifiable {
     public var trailerCount: Int?
     /// Gets or sets the trickplay manifest.
     public var trickplay: [String: [String: TrickplayInfo]]?
-    /// The base item kind.
+    /// Gets or sets the type.
     public var type: BaseItemKind?
     /// Gets or sets the user data for this item based on the user it's being requested for.
     public var userData: UserItemDataDto?

Sources/Entities/BaseItemPerson.swift

@@ -20,7 +20,7 @@ public struct BaseItemPerson: Codable, Hashable, Identifiable {
     public var primaryImageTag: String?
     /// Gets or sets the role.
     public var role: String?
-    /// The person kind.
+    /// Gets or sets the type.
     public var type: PersonKind?
 
     /// Gets or sets the primary image blurhash.

Sources/Entities/DisplayPreferencesDto.swift

@@ -26,15 +26,15 @@ public struct DisplayPreferencesDto: Codable, Hashable, Identifiable {
     public var isRememberIndexing: Bool?
     /// Gets or sets a value indicating whether [remember sorting].
     public var isRememberSorting: Bool?
-    /// An enum representing the axis that should be scrolled.
+    /// Gets or sets the scroll direction.
     public var scrollDirection: ScrollDirection?
     /// Gets or sets a value indicating whether to show backdrops on this item.
     public var isShowBackdrop: Bool?
     /// Gets or sets a value indicating whether [show sidebar].
     public var isShowSidebar: Bool?
     /// Gets or sets the sort by.
     public var sortBy: String?
-    /// An enum representing the sorting order.
+    /// Gets or sets the sort order.
     public var sortOrder: SortOrder?
     /// Gets or sets the type of the view.
     public var viewType: String?

Sources/Entities/MediaSegmentDto.swift

@@ -18,7 +18,7 @@ public struct MediaSegmentDto: Codable, Hashable, Identifiable {
     public var itemID: String?
     /// Gets or sets the start of the segment.
     public var startTicks: Int?
-    /// Defines the types of content an individual Jellyfin.Data.Entities.MediaSegment represents.
+    /// Gets or sets the type of content this segment defines.
     public var type: MediaSegmentType?
 
     public init(endTicks: Int? = nil, id: String? = nil, itemID: String? = nil, startTicks: Int? = nil, type: MediaSegmentType? = nil) {

Sources/Entities/MediaStream.swift

@@ -12,7 +12,7 @@ import Foundation
 public struct MediaStream: Codable, Hashable {
     /// Gets or sets the aspect ratio.
     public var aspectRatio: String?
-    /// An enum representing formats of spatial audio.
+    /// Gets the audio spatial format.
     public var audioSpatialFormat: AudioSpatialFormat?
     /// Gets or sets the average frame rate.
     public var averageFrameRate: Float?
@@ -125,9 +125,9 @@ public struct MediaStream: Codable, Hashable {
     public var type: MediaStreamType?
     /// Gets the video dovi title.
     public var videoDoViTitle: String?
-    /// An enum representing video ranges.
+    /// Gets the video range.
     public var videoRange: VideoRange?
-    /// An enum representing types of video ranges.
+    /// Gets the video range type.
     public var videoRangeType: VideoRangeType?
     /// Gets or sets the width.
     public var width: Int?

Sources/Entities/OpenLiveStreamDto.swift

@@ -14,7 +14,20 @@ public struct OpenLiveStreamDto: Codable, Hashable {
     public var isAlwaysBurnInSubtitleWhenTranscoding: Bool?
     /// Gets or sets the audio stream index.
     public var audioStreamIndex: Int?
-    /// Gets or sets the device profile.
+    /// A MediaBrowser.Model.Dlna.DeviceProfile represents a set of metadata which determines which content a certain device is able to
+    /// play.
+    ///
+    /// <br />
+    ///
+    /// Specifically, it defines the supported <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.ContainerProfiles">containers</see> and
+    ///
+    /// <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.CodecProfiles">codecs</see> (video and/or audio, including codec profiles and
+    /// levels)
+    ///
+    /// the device is able to direct play (without transcoding or remuxing),
+    ///
+    /// as well as which <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.TranscodingProfiles">containers/codecs to transcode to</see> in
+    /// case it isn't.
     public var deviceProfile: DeviceProfile?
     /// Gets or sets the device play protocols.
     public var directPlayProtocols: [MediaProtocol]?

Sources/Entities/PlaybackInfoDto.swift

@@ -20,7 +20,20 @@ public struct PlaybackInfoDto: Codable, Hashable {
     public var audioStreamIndex: Int?
     /// Gets or sets a value indicating whether to auto open the live stream.
     public var isAutoOpenLiveStream: Bool?
-    /// Gets or sets the device profile.
+    /// A MediaBrowser.Model.Dlna.DeviceProfile represents a set of metadata which determines which content a certain device is able to
+    /// play.
+    ///
+    /// <br />
+    ///
+    /// Specifically, it defines the supported <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.ContainerProfiles">containers</see> and
+    ///
+    /// <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.CodecProfiles">codecs</see> (video and/or audio, including codec profiles and
+    /// levels)
+    ///
+    /// the device is able to direct play (without transcoding or remuxing),
+    ///
+    /// as well as which <see cref="P:MediaBrowser.Model.Dlna.DeviceProfile.TranscodingProfiles">containers/codecs to transcode to</see> in
+    /// case it isn't.
     public var deviceProfile: DeviceProfile?
     /// Gets or sets a value indicating whether to enable direct play.
     public var enableDirectPlay: Bool?