Merge pull request #99 from rryam/agent/language-tag-endpoint

Add best supported language endpoint

Author: rudrankriyam

Sources/MusadoraKit/Catalog/MCatalog+Language.swift

@@ -0,0 +1,122 @@
+//
+//  MCatalog+Language.swift
+//  MusadoraKit
+//
+//  Created by Claude on 05/08/26.
+//
+
+import Foundation
+
+/// `LanguageTagResponse` is a struct that decodes the response from the best supported language endpoint.
+///
+/// This structure corresponds to the response you would receive when asking the Apple Music API
+/// for the best supported language tag of a storefront.
+///
+/// - Note: Apple's documentation refers to this object as `LangageTagResponse` (sic);
+///         MusadoraKit spells it correctly.
+struct LanguageTagResponse: Decodable {
+  /// The results container returned by the endpoint.
+  let results: Results
+
+  /// The container holding the resolved language tag.
+  struct Results: Decodable {
+    /// The best language tag supported by the storefront, as an RFC 4646 language tag.
+    let tag: String
+  }
+}
+
+public extension MCatalog {
+  /// Fetches the best supported language tag for a storefront of Apple Music.
+  ///
+  /// Pass the language tags your app accepts, in order of preference, and the Apple Music API
+  /// resolves them against the storefront's supported language tags server-side. The returned
+  /// tag is the best match, ready to use as the localization (`l`) parameter in subsequent
+  /// catalog requests.
+  ///
+  /// Example usage:
+  ///
+  /// ```swift
+  /// do {
+  ///     let languageTag = try await MCatalog.bestLanguageTag(for: "in", accepting: ["hi", "en-GB"])
+  ///     print(languageTag) // "hi"
+  /// } catch {
+  ///     print("Failed to fetch the best language tag: \(error)")
+  /// }
+  /// ```
+  ///
+  /// In the above example, "in" is the identifier for the India storefront, and the accepted
+  /// languages prefer Hindi over British English.
+  ///
+  /// - Parameters:
+  ///   - storefront: The identifier for the storefront you want to resolve the language for. This is usually a country code.
+  ///   - languages: The language tags your app accepts, in order of preference.
+  ///   - localization: An optional localization to use for the request. Defaults to `nil`.
+  /// - Returns: The best language tag supported by the storefront, as an RFC 4646 language tag.
+  /// - Throws: `MusadoraKitError.languageTagsMissing` if `languages` is empty, or an error if there was a problem with the network request or decoding the response.
+  static func bestLanguageTag(for storefront: String, accepting languages: [String], localization: String? = nil) async throws -> String {
+    let url = try bestLanguageTagURL(storefront: storefront, languages: languages, localization: localization)
+
+    let request = MusicDataRequest(urlRequest: .init(url: url))
+    let response = try await request.response()
+    let languageTag = try JSONDecoder().decode(LanguageTagResponse.self, from: response.data)
+
+    return languageTag.results.tag
+  }
+
+  /// Fetches the best supported language tag for a storefront of Apple Music,
+  /// based on the user's preferred languages.
+  ///
+  /// This convenience method uses `Locale.preferredLanguages` — the user's preferred
+  /// languages, in order — as the accepted language tags.
+  ///
+  /// Example usage:
+  ///
+  /// ```swift
+  /// do {
+  ///     let languageTag = try await MCatalog.bestLanguageTag(for: "in")
+  ///     print(languageTag)
+  /// } catch {
+  ///     print("Failed to fetch the best language tag: \(error)")
+  /// }
+  /// ```
+  ///
+  /// - Parameter storefront: The identifier for the storefront you want to resolve the language for. This is usually a country code.
+  /// - Returns: The best language tag supported by the storefront, as an RFC 4646 language tag.
+  /// - Throws: `MusadoraKitError.languageTagsMissing` if `Locale.preferredLanguages` is empty, or an error if there was a problem with the network request or decoding the response.
+  static func bestLanguageTag(for storefront: String) async throws -> String {
+    try await bestLanguageTag(for: storefront, accepting: Locale.preferredLanguages)
+  }
+}
+
+extension MCatalog {
+  /// Returns the URL for fetching the best supported language tag for the specified storefront.
+  ///
+  /// - Parameters:
+  ///   - storefront: The identifier for the storefront.
+  ///   - languages: The language tags to accept, in order of preference.
+  ///   - localization: An optional localization to use for the request.
+  ///
+  /// - Returns: The URL for fetching the best supported language tag for the specified storefront.
+  internal static func bestLanguageTagURL(storefront: String, languages: [String], localization: String?) throws -> URL {
+    guard !languages.isEmpty else {
+      throw MusadoraKitError.languageTagsMissing
+    }
+
+    var urlComponents = AppleMusicURLComponents()
+    urlComponents.path = "language/\(storefront)/tag"
+
+    var queryItems = [URLQueryItem(name: "acceptLanguage", value: languages.joined(separator: ","))]
+
+    if let localization, !localization.isEmpty {
+      queryItems.append(URLQueryItem(name: "l", value: localization))
+    }
+
+    urlComponents.queryItems = queryItems
+
+    guard let url = urlComponents.url else {
+      throw URLError(.badURL)
+    }
+
+    return url
+  }
+}

Sources/MusadoraKit/Models/MusadoraKitError.swift

@@ -30,6 +30,9 @@ public enum MusadoraKitError: Error, Equatable {
   /// One or more IDs must be specified for the operation.
   case idMissing
 
+  /// One or more language tags must be specified for the operation.
+  case languageTagsMissing
+
   /// The platform does not support this operation.
   case platformNotSupported
 
@@ -93,6 +96,8 @@ extension MusadoraKitError: CustomStringConvertible {
       return "A monthly summary period could not be determined from the provided date context."
     case .idMissing:
       return "One or more IDs must be specified for the operation."
+    case .languageTagsMissing:
+      return "One or more language tags must be specified for the operation."
     case .platformNotSupported:
       return "This operation is only available on iOS."
     case let .ratingNotFound(id):

Tests/MusadoraKitTests/Storefronts/LanguageTagEndpointTests.swift

@@ -0,0 +1,59 @@
+//
+//  LanguageTagEndpointTests.swift
+//  MusadoraKitTests
+//
+//  Created by Claude on 05/08/26.
+//
+
+import Foundation
+@testable import MusadoraKit
+import Testing
+
+@Suite
+struct LanguageTagEndpointTests {
+  @Test
+  func bestLanguageTagEndpointForStorefront() throws {
+    let url = try MCatalog.bestLanguageTagURL(storefront: "in", languages: ["hi", "en-GB"], localization: nil)
+    expectEndpoint(url, equals: "https://api.music.apple.com/v1/language/in/tag?acceptLanguage=hi,en-GB")
+  }
+
+  @Test
+  func bestLanguageTagEndpointWithLocalization() throws {
+    let url = try MCatalog.bestLanguageTagURL(storefront: "in", languages: ["hi", "en-GB"], localization: "hi")
+    expectEndpoint(url, equals: "https://api.music.apple.com/v1/language/in/tag?acceptLanguage=hi,en-GB&l=hi")
+  }
+
+  @Test
+  func bestLanguageTagEndpointForSingleLanguage() throws {
+    let url = try MCatalog.bestLanguageTagURL(storefront: "jp", languages: ["ja"], localization: nil)
+    expectEndpoint(url, equals: "https://api.music.apple.com/v1/language/jp/tag?acceptLanguage=ja")
+  }
+
+  @Test
+  func bestLanguageTagEndpointIgnoresEmptyLocalization() throws {
+    let url = try MCatalog.bestLanguageTagURL(storefront: "us", languages: ["en-US"], localization: "")
+    expectEndpoint(url, equals: "https://api.music.apple.com/v1/language/us/tag?acceptLanguage=en-US")
+  }
+
+  @Test
+  func bestLanguageTagEndpointEmptyLanguagesThrows() {
+    #expect(throws: MusadoraKitError.languageTagsMissing) {
+      _ = try MCatalog.bestLanguageTagURL(storefront: "in", languages: [], localization: nil)
+    }
+  }
+
+  @Test
+  func decodingLanguageTagResponse() throws {
+    let json = Data(#"{"results":{"tag":"en-GB"}}"#.utf8)
+    let response = try JSONDecoder().decode(LanguageTagResponse.self, from: json)
+    #expect(response.results.tag == "en-GB")
+  }
+
+  @Test
+  func decodingLanguageTagResponseWithoutTagThrows() {
+    let json = Data(#"{"results":{}}"#.utf8)
+    #expect(throws: Error.self) {
+      _ = try JSONDecoder().decode(LanguageTagResponse.self, from: json)
+    }
+  }
+}