/macos/RoonKit/Sources/RoonKit/Services/BrowseService.swift at 51147fe9fd0ea6af0d25c6a420e56ca674f31e12

// Copyright 2025 Shota FUJI
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// SPDX-License-Identifier: Apache-2.0

public struct BrowseService {
	public static let id = "com.roonlabs.browse:1"

	public enum ItemHint: LosslessStringConvertible, Codable, Hashable, Sendable {
		case unknown(String)
		case action, actionList
		case list
		case header

		public var description: String {
			switch self {
			case .action:
				"action"
			case .actionList:
				"action_list"
			case .header:
				"header"
			case .list:
				"list"
			case .unknown(let string):
				string
			}
		}

		public init(_ description: String) {
			switch description {
			case "action":
				self = .action
			case "action_list":
				self = .actionList
			case "header":
				self = .header
			case "list":
				self = .list
			default:
				self = .unknown(description)
			}
		}

		public init(from decoder: any Decoder) throws {
			let value = try decoder.singleValueContainer()
			let string = try value.decode(String.self)

			self.init(string)
		}

		public func encode(to encoder: any Encoder) throws {
			var value = encoder.singleValueContainer()
			try value.encode(self.description)
		}
	}

	public struct InputPrompt: Codable, Hashable, Sendable {
		public let prompt: String
		public let action: String
		public let value: String?
		let _isPassword: Bool?

		public var isPassword: Bool {
			_isPassword ?? false
		}

		public enum CodingKeys: String, CodingKey {
			case prompt = "prompt"
			case action = "action"
			case value = "value"
			case _isPassword = "is_password"
		}
	}

	private static func stripInternalLinks(text: String) -> String {
		var source = text[...]
		var components: [Substring] = []

		while true {
			guard let starts = source.firstRange(of: "[[") else {
				components.append(source)
				break
			}

			guard let idEnds = source.firstIndex(of: "|") else {
				components.append(source)
				break
			}

			guard let ends = source.firstRange(of: "]]") else {
				components.append(source)
				break
			}

			guard starts.upperBound < idEnds, idEnds < ends.lowerBound else {
				components.append(source)
				break
			}

			components.append(source[..<starts.lowerBound])
			components.append(source[source.index(after: idEnds)..<ends.lowerBound])
			if ends.upperBound >= source.index(before: source.endIndex) {
				break
			}

			source = source[ends.upperBound...]
		}

		return components.joined()
	}

	public struct Item: Codable, Hashable, Sendable {
		public let title: String
		public let subtitle: String?
		public let imageKey: ImageService.Key?
		public let itemKey: String?
		public let hint: ItemHint?
		public let inputPrompt: InputPrompt?

		public enum CodingKeys: String, CodingKey {
			case title = "title"
			case subtitle = "subtitle"
			case imageKey = "image_key"
			case itemKey = "item_key"
			case hint = "hint"
			case inputPrompt = "input_prompt"
		}

		public init(
			title: String,
			subtitle: String? = nil,
			imageKey: ImageService.Key? = nil,
			itemKey: String? = nil,
			hint: ItemHint? = nil,
			inputPrompt: InputPrompt? = nil
		) {
			self.title = title
			self.subtitle = subtitle
			self.imageKey = imageKey
			self.itemKey = itemKey
			self.hint = hint
			self.inputPrompt = inputPrompt
		}

		/// Newer browsing pages, such as third-party cloud service's pages, *may* return
		/// `[[ID|label]]` formatted text for subtitle. As the text will be nearly unreadable,
		/// this helper getter function parses that and returns label part. The format is not specified.
		public var correctedSubtitle: String? {
			guard let subtitle = subtitle else {
				return nil
			}

			return stripInternalLinks(text: subtitle)
		}
	}

	public enum ListHint: LosslessStringConvertible, Codable, Sendable {
		case unknown(String)
		case actionList

		public var description: String {
			switch self {
			case .actionList:
				"action_list"
			case .unknown(let string):
				string
			}
		}

		public init(_ description: String) {
			switch description {
			case "action_list":
				self = .actionList
			default:
				self = .unknown(description)
			}
		}

		public init(from decoder: any Decoder) throws {
			let value = try decoder.singleValueContainer()
			let string = try value.decode(String.self)

			self.init(string)
		}

		public func encode(to encoder: any Encoder) throws {
			var value = encoder.singleValueContainer()
			try value.encode(self.description)
		}
	}

	public struct List: Codable, Sendable {
		public let title: String
		public let subtitle: String?
		public let imageKey: ImageService.Key?
		public let displayOffset: Int?
		public let hint: ListHint?

		let _count: UInt?
		let _level: UInt?

		public var count: UInt {
			_count ?? 0
		}

		public var level: UInt {
			_level ?? 0
		}

		public enum CodingKeys: String, CodingKey {
			case title = "title"
			case _count = "count"
			case subtitle = "subtitle"
			case imageKey = "image_key"
			case _level = "level"
			case displayOffset = "display_offset"
			case hint = "hint"
		}

		/// Newer browsing pages, such as third-party cloud service's pages, *may* return
		/// `[[ID|label]]` formatted text for subtitle. As the text will be nearly unreadable,
		/// this helper getter function parses that and returns label part. The format is not specified.
		public var correctedSubtitle: String? {
			guard let subtitle = subtitle else {
				return nil
			}

			return stripInternalLinks(text: subtitle)
		}
	}

	public enum Hierarchy: String, Codable {
		case browse, playlists, settings, albums
		case artists, genres, composers, search
		case internetRadio = "internet_radio"
	}
}

// MARK: - Move server-side browsing location

extension BrowseService {
	public enum BrowseAction: String, Codable {
		case message, none, list
		case replaceItem = "replace_item"
		case removeItem = "remove_item"
	}

	public struct BrowseRequest: Codable {
		public let hierarchy: Hierarchy
		public let multiSessionKey: String?
		public let itemKey: String?
		public let input: String?
		public let zoneOrOutputID: String?
		public let popAll: Bool?
		public let popLevels: UInt?
		public let refreshList: Bool?

		public enum CodingKeys: String, CodingKey {
			case hierarchy = "hierarchy"
			case multiSessionKey = "multi_session_key"
			case itemKey = "item_key"
			case input = "input"
			case zoneOrOutputID = "zone_or_output_id"
			case popAll = "pop_all"
			case popLevels = "pop_levels"
			case refreshList = "refresh_list"
		}

		public init(
			hierarchy: Hierarchy,
			multiSessionKey: String? = nil,
			itemKey: String? = nil,
			input: String? = nil,
			zoneOrOutputID: String? = nil,
			popAll: Bool? = nil,
			popLevels: UInt? = nil,
			refreshList: Bool? = nil
		) {
			self.hierarchy = hierarchy
			self.multiSessionKey = multiSessionKey
			self.itemKey = itemKey
			self.input = input
			self.zoneOrOutputID = zoneOrOutputID
			self.popAll = popAll
			self.popLevels = popLevels
			self.refreshList = refreshList
		}
	}

	public struct BrowseResponse: Codable {
		public let action: BrowseAction
		public let item: Item?
		public let list: List?
		public let message: String?
		let _isError: Bool?

		public var isError: Bool {
			_isError ?? false
		}

		public enum CodingKeys: String, CodingKey {
			case action = "action"
			case item = "item"
			case list = "list"
			case message = "message"
			case _isError = "is_error"
		}

		public enum DecodeError: Error {
			case nonSuccess
			case invalidBody(Moo.JsonBodyError)
		}

		public init(_ msg: Moo) throws(DecodeError) {
			guard msg.service == "Success" else {
				throw .nonSuccess
			}

			do {
				self = try msg.json(type: Self.self)
			} catch {
				throw .invalidBody(error)
			}
		}
	}
}

extension Moo {
	public init(browse: BrowseService.BrowseRequest) throws {
		try self.init(jsonBody: browse, service: "\(BrowseService.id)/browse")
	}
}

// MARK: - Load items at server-side browsing location

extension BrowseService {
	public struct LoadRequest: Codable {
		public let hierarchy: Hierarchy
		public let multiSessionKey: String?
		public let displayOffset: Int?
		public let level: UInt?
		public let offset: Int?
		public let count: UInt?

		public enum CodingKeys: String, CodingKey {
			case hierarchy = "hierarchy"
			case multiSessionKey = "multi_session_key"
			case displayOffset = "display_offset"
			case level = "level"
			case offset = "offset"
			case count = "count"
		}

		public init(
			hierarchy: Hierarchy,
			multiSessionKey: String? = nil,
			displayOffset: Int? = nil,
			level: UInt? = 0,
			offset: Int? = 0,
			count: UInt? = nil,
		) {
			self.hierarchy = hierarchy
			self.multiSessionKey = multiSessionKey
			self.displayOffset = displayOffset
			self.level = level
			self.offset = offset
			self.count = count
		}
	}

	public struct LoadResponse: Codable, Sendable {
		public let items: [Item]
		let _offset: Int?
		public let list: List

		public var offset: Int {
			_offset ?? 0
		}

		public enum CodingKeys: String, CodingKey {
			case items = "items"
			case _offset = "offset"
			case list = "list"
		}

		public enum DecodeError: Error {
			case nonSuccess
			case invalidBody(Moo.JsonBodyError)
		}

		public init(_ msg: Moo) throws(DecodeError) {
			guard msg.service == "Success" else {
				throw .nonSuccess
			}

			do {
				self = try msg.json(type: Self.self)
			} catch {
				throw .invalidBody(error)
			}
		}
	}
}

extension Moo {
	public init(load: BrowseService.LoadRequest) throws {
		try self.init(jsonBody: load, service: "\(BrowseService.id)/load")
	}
}