@wwdrew/expo-apple-music 1.0.0

package/ios/RestCatalogSearchStore.swift

@@ -0,0 +1,62 @@
+// RestCatalogSearchStore.swift
+// Catalog search via Apple Music REST API (aligned with Android catalog paths).
+
+import Foundation
+
+@available(iOS 16.0, *)
+struct RestCatalogSearchStore: CatalogSearchStore {
+
+  func search(
+    term: String,
+    types: [String],
+    options: CatalogService.SearchOptions
+  ) async throws -> CatalogService.SearchResult {
+    let storefront = StorefrontService.getCatalogStorefront()
+    let typeParam = Array(Set(types.compactMap { catalogSearchTypeParam($0) })).sorted().joined(
+      separator: ",")
+    let typesQuery = typeParam.isEmpty ? "songs,albums" : typeParam
+
+    let json = try await AppleMusicRestClient.get(
+      path: "/v1/catalog/\(storefront)/search",
+      query: [
+        "term": term,
+        "types": typesQuery,
+        "limit": "\(options.limit)",
+        "offset": "\(options.offset)",
+      ]
+    )
+
+    let results = json["results"] as? [String: Any] ?? [:]
+
+    return CatalogService.SearchResult(
+      songs: parseSearchBucket(results: results, key: "songs", mapper: RestJsonMapper.mapSong),
+      albums: parseSearchBucket(results: results, key: "albums", mapper: RestJsonMapper.mapAlbum),
+      artists: parseSearchBucket(results: results, key: "artists", mapper: RestJsonMapper.mapArtist),
+      playlists: parseSearchBucket(
+        results: results, key: "playlists", mapper: RestJsonMapper.mapPlaylist),
+      stations: parseSearchBucket(results: results, key: "stations", mapper: RestJsonMapper.mapStation),
+      musicVideos: parseSearchBucket(
+        results: results, key: "music-videos", mapper: RestJsonMapper.mapMusicVideo)
+    )
+  }
+
+  private func catalogSearchTypeParam(_ type: String) -> String? {
+    switch type {
+    case "songs", "albums", "artists", "playlists", "stations", "music-videos": return type
+    default: return nil
+    }
+  }
+
+  private func parseSearchBucket(
+    results: [String: Any],
+    key: String,
+    mapper: ([String: Any]) -> [String: Any]
+  ) -> [[String: Any]] {
+    guard let bucket = results[key] as? [String: Any],
+      let data = bucket["data"] as? [[String: Any]]
+    else {
+      return []
+    }
+    return data.map(mapper)
+  }
+}

package/ios/RestJsonMapper.swift

@@ -0,0 +1,268 @@
+// RestJsonMapper.swift
+// Maps Apple Music API JSON objects to bridge dictionaries (matches Android mapper).
+// Golden REST cases: fixtures/*.json + fixtures/expected/*.json — see docs/BRIDGE_CONTRACT.md.
+
+import Foundation
+
+@available(iOS 16.0, *)
+enum RestJsonMapper {
+
+  static func mapAlbum(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let trackCount: Int
+    if let count = attributes["trackCount"] as? Int {
+      trackCount = count
+    } else if let count = attributes["trackCount"] as? Double {
+      trackCount = Int(count)
+    } else {
+      trackCount = 0
+    }
+    return [
+      "id": resource["id"] as? String ?? "",
+      "title": attributes["name"] as? String ?? "",
+      "artistName": attributes["artistName"] as? String ?? "",
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+      "trackCount": trackCount,
+    ]
+  }
+
+  static func mapSong(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let id = catalogPlaybackId(resource) ?? (resource["id"] as? String ?? "")
+    return [
+      "id": id,
+      "title": attributes["name"] as? String ?? "",
+      "artistName": attributes["artistName"] as? String ?? "",
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+      "duration": durationMillis(attributes),
+    ]
+  }
+
+  static func mapArtist(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    return [
+      "id": resource["id"] as? String ?? "",
+      "name": attributes["name"] as? String ?? "",
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+    ]
+  }
+
+  static func mapRecentResource(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let apiType = resource["type"] as? String ?? ""
+    let itemType: String
+    if apiType.contains("album") {
+      itemType = "album"
+    } else if apiType.contains("playlist") {
+      itemType = "playlist"
+    } else if apiType.contains("station") {
+      itemType = "station"
+    } else {
+      itemType = "unknown"
+    }
+
+    var subtitle = attributes["artistName"] as? String ?? ""
+    if subtitle.isEmpty {
+      subtitle = attributes["curatorName"] as? String ?? ""
+    }
+    if subtitle.isEmpty, let description = attributes["description"] as? [String: Any] {
+      subtitle = description["standard"] as? String ?? ""
+    }
+
+    return [
+      "id": resource["id"] as? String ?? "",
+      "title": attributes["name"] as? String ?? "",
+      "subtitle": subtitle,
+      "type": itemType,
+    ]
+  }
+
+  static func mapRecentlyPlayed(_ resource: [String: Any]) -> [String: Any] {
+    mapRecentResource(resource)
+  }
+
+  static func mapPlaylist(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    var trackCount = 0
+    if let count = attributes["trackCount"] as? Int {
+      trackCount = count
+    } else if let count = attributes["trackCount"] as? Double {
+      trackCount = Int(count)
+    }
+    var description = attributes["description"] as? String ?? ""
+    if description.isEmpty, let desc = attributes["description"] as? [String: Any] {
+      description = desc["standard"] as? String ?? ""
+    }
+    return [
+      "id": resource["id"] as? String ?? "",
+      "name": attributes["name"] as? String ?? "",
+      "description": description,
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+      "trackCount": trackCount,
+    ]
+  }
+
+  static func mapMusicVideo(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let id = catalogPlaybackId(resource) ?? (resource["id"] as? String ?? "")
+    return [
+      "id": id,
+      "title": attributes["name"] as? String ?? "",
+      "artistName": attributes["artistName"] as? String ?? "",
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+      "duration": durationMillis(attributes),
+    ]
+  }
+
+  static func mapStation(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    return [
+      "id": resource["id"] as? String ?? "",
+      "name": attributes["name"] as? String ?? "",
+      "artworkUrl": artworkUrl(attributes["artwork"] as? [String: Any]),
+    ]
+  }
+
+  private static func catalogPlaybackId(_ resource: [String: Any]) -> String? {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    guard let playParams = attributes["playParams"] as? [String: Any] else { return nil }
+    if let id = playParams["id"] as? String, !id.isEmpty { return id }
+    if let catalogId = playParams["catalogId"] as? String, !catalogId.isEmpty { return catalogId }
+    return nil
+  }
+
+  /// Candidate catalog song ids for MusicKit lookup (playback id, resource id, playParams).
+  static func catalogSongLookupIds(primaryId: String, resource: [String: Any]) -> [String] {
+    var ids: [String] = []
+    func append(_ value: String?) {
+      guard let value, !value.isEmpty, !ids.contains(value) else { return }
+      ids.append(value)
+    }
+    append(primaryId)
+    append(resource["id"] as? String)
+    append(catalogPlaybackId(resource))
+    return ids
+  }
+
+  private static func durationMillis(_ attributes: [String: Any]) -> Int {
+    if let millis = attributes["durationInMillis"] as? Int {
+      return millis
+    }
+    if let millis = attributes["durationInMillis"] as? Double {
+      return Int(millis)
+    }
+    if let duration = attributes["duration"] as? Double {
+      return Int(duration * 1000)
+    }
+    return 0
+  }
+
+  private static func artworkUrl(_ artwork: [String: Any]?, width: Int = 200, height: Int = 200) -> String {
+    guard let artwork, let template = artwork["url"] as? String, !template.isEmpty else {
+      return ""
+    }
+    return template
+      .replacingOccurrences(of: "{w}", with: "\(width)")
+      .replacingOccurrences(of: "{h}", with: "\(height)")
+  }
+
+  static func mapRating(_ json: [String: Any]) -> [String: Any]? {
+    guard let data = json["data"] as? [[String: Any]], let first = data.first else {
+      return nil
+    }
+    let attributes = first["attributes"] as? [String: Any] ?? [:]
+    let value = attributes["value"] as? Int ?? (attributes["value"] as? Double).map { Int($0) }
+    guard let value else { return nil }
+    return [
+      "id": first["id"] as? String ?? "",
+      "value": value,
+    ]
+  }
+
+  static func mapRecommendation(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let titleDict = attributes["title"] as? [String: Any]
+    let title = titleDict?["stringForDisplay"] as? String ?? ""
+    let resourceTypes = attributes["resourceTypes"] as? [String] ?? []
+    let contents = mapRecommendationContents(resource)
+    return [
+      "id": resource["id"] as? String ?? "",
+      "title": title,
+      "resourceTypes": resourceTypes,
+      "playlists": contents.playlists,
+      "albums": contents.albums,
+      "stations": contents.stations,
+    ]
+  }
+
+  static func mapReplaySummary(_ resource: [String: Any]) -> [String: Any] {
+    let attributes = resource["attributes"] as? [String: Any] ?? [:]
+    let year = attributes["year"] as? Int ?? (attributes["year"] as? Double).map { Int($0) }
+    var result: [String: Any] = [
+      "id": resource["id"] as? String ?? "",
+      "type": resource["type"] as? String ?? "",
+      "name": attributes["name"] as? String ?? "",
+      "topSongs": mapRelationshipResources(resource, key: "top-songs", mapper: mapSong),
+      "topAlbums": mapRelationshipResources(resource, key: "top-albums", mapper: mapAlbum),
+      "topArtists": mapRelationshipResources(resource, key: "top-artists", mapper: mapArtist),
+    ]
+    if let year {
+      result["year"] = year
+    }
+    return result
+  }
+
+  private struct RecommendationContents {
+    let playlists: [[String: Any]]
+    let albums: [[String: Any]]
+    let stations: [[String: Any]]
+  }
+
+  private static func mapRecommendationContents(_ resource: [String: Any]) -> RecommendationContents {
+    var playlists: [[String: Any]] = []
+    var albums: [[String: Any]] = []
+    var stations: [[String: Any]] = []
+    guard let relationships = resource["relationships"] as? [String: Any],
+      let contents = relationships["contents"] as? [String: Any],
+      let data = contents["data"] as? [[String: Any]]
+    else {
+      return RecommendationContents(playlists: playlists, albums: albums, stations: stations)
+    }
+    for item in data {
+      let type = item["type"] as? String ?? ""
+      if type.contains("playlist") {
+        playlists.append(mapPlaylist(item))
+      } else if type.contains("album") {
+        albums.append(mapAlbum(item))
+      } else if type.contains("station") {
+        stations.append(mapStation(item))
+      }
+    }
+    return RecommendationContents(playlists: playlists, albums: albums, stations: stations)
+  }
+
+  private static func mapRelationshipResources(
+    _ resource: [String: Any],
+    key: String,
+    mapper: ([String: Any]) -> [String: Any]
+  ) -> [[String: Any]] {
+    guard let relationships = resource["relationships"] as? [String: Any],
+      let relation = relationships[key] as? [String: Any],
+      let data = relation["data"] as? [[String: Any]]
+    else {
+      return []
+    }
+    return data.map(mapper)
+  }
+
+  static func buildIdsQuery(_ resourceIds: [String: [String]]) -> [String: String] {
+    var query: [String: String] = [:]
+    for (type, ids) in resourceIds {
+      let filtered = ids.filter { !$0.isEmpty }
+      if !filtered.isEmpty {
+        query["ids[\(type)]"] = filtered.joined(separator: ",")
+      }
+    }
+    return query
+  }
+}

package/ios/StorefrontService.swift

@@ -0,0 +1,55 @@
+// StorefrontService.swift
+// Resolves the user's Apple Music storefront via MusicKit-authenticated API requests.
+
+import Foundation
+import MusicKit
+
+@available(iOS 16.0, *)
+enum StorefrontService {
+
+  enum StorefrontError: LocalizedError {
+    case invalidResponse
+    case unauthorized
+
+    var errorDescription: String? {
+      switch self {
+      case .invalidResponse: return "Invalid storefront response from Apple Music"
+      case .unauthorized: return "Not authorized for Apple Music"
+      }
+    }
+  }
+
+  /// Catalog REST paths — cached storefront or device locale (no music user token).
+  static func getCatalogStorefront() -> String {
+    if let cached = AuthenticatedSessionCache.cachedStorefrontId() {
+      return cached
+    }
+    return localeStorefrontId()
+  }
+
+  static func getStorefrontId(musicUserToken: String) async throws -> String {
+    if let cached = AuthenticatedSessionCache.cachedStorefrontId() {
+      return cached
+    }
+
+    let session = AuthenticatedSession.current
+    if session.hasDeveloperToken {
+      let data = try await AppleMusicRestClient.getDataArray(
+        path: "/v1/me/storefront",
+        musicUserToken: musicUserToken)
+      if let id = data.first?["id"] as? String, !id.isEmpty {
+        AuthenticatedSessionCache.setStorefrontId(id)
+        return id
+      }
+    }
+    return localeStorefrontId()
+  }
+
+  /// Fallback when MusicKit auto-token or `/v1/me/storefront` is unavailable (catalog REST only).
+  static func localeStorefrontId() -> String {
+    if let region = Locale.current.region?.identifier, !region.isEmpty {
+      return region.lowercased()
+    }
+    return "us"
+  }
+}

package/ios/SubscriptionService.swift

@@ -0,0 +1,119 @@
+// SubscriptionService.swift
+// Handles Apple Music authorization and subscription status checks.
+
+import Foundation
+import MusicKit
+import StoreKit
+
+@available(iOS 16.0, *)
+final class SubscriptionService {
+
+  // MARK: - Authorization
+
+  enum AuthorizationStatus: String {
+    case authorized
+    case denied
+    case notDetermined
+    case restricted
+    case unknown
+  }
+
+  func requestAuthorization() async -> AuthorizationStatus {
+    await withCheckedContinuation { continuation in
+      SKCloudServiceController.requestAuthorization { status in
+        let result: AuthorizationStatus
+        switch status {
+        case .authorized: result = .authorized
+        case .denied: result = .denied
+        case .notDetermined: result = .notDetermined
+        case .restricted: result = .restricted
+        @unknown default: result = .unknown
+        }
+        continuation.resume(returning: result)
+      }
+    }
+  }
+
+  /// Fetches a music user token when a developer JWT is available (not persisted by the module).
+  func fetchMusicUserToken(developerToken: String) async -> String? {
+    guard !developerToken.isEmpty else { return nil }
+    return await withCheckedContinuation { continuation in
+      SKCloudServiceController().requestUserToken(forDeveloperToken: developerToken) { token, _ in
+        if let token, !token.isEmpty {
+          continuation.resume(returning: token)
+        } else {
+          continuation.resume(returning: nil)
+        }
+      }
+    }
+  }
+
+  // MARK: - Subscription Check
+
+  struct SubscriptionDetails {
+    let canPlayCatalogContent: Bool
+    let canBecomeSubscriber: Bool
+    let hasCloudLibraryEnabled: Bool
+    let isMusicCatalogSubscriptionEligible: Bool
+
+    func toDictionary() -> [String: Any] {
+      [
+        "canPlayCatalogContent": canPlayCatalogContent,
+        "canBecomeSubscriber": canBecomeSubscriber,
+        "hasCloudLibraryEnabled": hasCloudLibraryEnabled,
+        "isMusicCatalogSubscriptionEligible": isMusicCatalogSubscriptionEligible,
+      ]
+    }
+  }
+
+  func checkSubscription() async throws -> SubscriptionDetails {
+    let subscription = try await MusicSubscription.current
+    return SubscriptionDetails(
+      canPlayCatalogContent: subscription.canPlayCatalogContent,
+      canBecomeSubscriber: subscription.canBecomeSubscriber,
+      hasCloudLibraryEnabled: subscription.hasCloudLibraryEnabled,
+      isMusicCatalogSubscriptionEligible: subscription.canBecomeSubscriber
+    )
+  }
+}
+
+// MARK: - Subscription Error Handling
+
+@available(iOS 16.0, *)
+extension SubscriptionService {
+
+  struct SubscriptionError: LocalizedError {
+    let code: String
+    let message: String
+    let failureReason: String?
+    let recoverySuggestion: String?
+    let helpAnchor: String?
+
+    var errorDescription: String? { message }
+
+    func toNSError() -> NSError {
+      var userInfo: [String: Any] = [NSLocalizedDescriptionKey: message]
+      if let reason = failureReason {
+        userInfo[NSLocalizedFailureReasonErrorKey] = reason
+      }
+      if let suggestion = recoverySuggestion {
+        userInfo[NSLocalizedRecoverySuggestionErrorKey] = suggestion
+      }
+      if let anchor = helpAnchor {
+        userInfo[NSHelpAnchorErrorKey] = anchor
+      }
+      return NSError(domain: "MusicSubscription", code: 0, userInfo: userInfo)
+    }
+  }
+
+  static func wrapSubscriptionError(_ error: Error) -> SubscriptionError? {
+    guard let subError = error as? MusicSubscription.Error else { return nil }
+    return SubscriptionError(
+      code: subError.rawValue,
+      message: subError.localizedDescription,
+      failureReason: subError.failureReason,
+      recoverySuggestion: subError.recoverySuggestion,
+      helpAnchor: subError.helpAnchor
+    )
+  }
+}

package/ios/bridge/ExpoBridgeCatalog.swift

@@ -0,0 +1,98 @@
+import Foundation
+
+@available(iOS 16.0, *)
+enum ExpoBridgeCatalog {
+  static func catalogSearch(
+    service: CatalogService,
+    term: String,
+    types: [String],
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let searchOptions = CatalogService.SearchOptions(limit: pagination.limit, offset: pagination.offset)
+      let result = try await service.search(term: term, types: types, options: searchOptions)
+      return BridgeResponses.catalogSearch(result)
+    }
+  }
+
+  static func getCatalogAlbumTracks(
+    service: CatalogService,
+    albumId: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let searchOptions = CatalogService.SearchOptions(limit: pagination.limit, offset: pagination.offset)
+      let songs = try await service.getAlbumTracks(albumId: albumId, options: searchOptions)
+      return BridgeResponses.songs(songs)
+    }
+  }
+
+  static func getCatalogArtistAlbums(
+    service: CatalogService,
+    artistId: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let searchOptions = CatalogService.SearchOptions(limit: pagination.limit, offset: pagination.offset)
+      let albums = try await service.getArtistAlbums(artistId: artistId, options: searchOptions)
+      return BridgeResponses.albums(albums)
+    }
+  }
+
+  static func getCatalogPlaylistTracks(
+    service: CatalogService,
+    playlistId: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let searchOptions = CatalogService.SearchOptions(limit: pagination.limit, offset: pagination.offset)
+      let songs = try await service.getPlaylistTracks(playlistId: playlistId, options: searchOptions)
+      return BridgeResponses.songs(songs)
+    }
+  }
+
+  static func getCatalogCharts(
+    service: CatalogService,
+    types: [String],
+    options: [String: Any]
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options as NSDictionary)
+      let searchOptions = CatalogService.SearchOptions(limit: pagination.limit, offset: pagination.offset)
+      let genre = options["genre"] as? String
+      let chart = options["chart"] as? String
+      let result = try await service.getCharts(types: types, options: searchOptions, genre: genre, chart: chart)
+      return BridgeResponses.catalogCharts(result)
+    }
+  }
+
+  static func getCatalogResources(
+    service: CatalogService,
+    type: String,
+    ids: [String]
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let items = try await service.getResources(type: type, ids: ids)
+      switch type {
+      case "songs":
+        return BridgeResponses.songs(items)
+      case "albums":
+        return BridgeResponses.albums(items)
+      case "artists":
+        return BridgeResponses.artists(items)
+      case "playlists":
+        return BridgeResponses.playlists(items)
+      case "stations":
+        return BridgeResponses.stations(items)
+      case "music-videos":
+        return BridgeResponses.musicVideos(items)
+      default:
+        throw CatalogService.CatalogServiceError.unknownResourceType(type)
+      }
+    }
+  }
+}

package/ios/bridge/ExpoBridgeHistory.swift

@@ -0,0 +1,71 @@
+import Foundation
+
+@available(iOS 16.0, *)
+enum ExpoBridgeHistory {
+  static func getRecentlyPlayedResources(
+    service: HistoryService,
+    musicUserToken: String
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let tracks = try await service.getRecentlyPlayedResources(musicUserToken: musicUserToken)
+      return BridgeResponses.recentlyPlayedResources(tracks)
+    }
+  }
+
+  static func getRecentlyPlayedTracks(
+    service: HistoryService,
+    musicUserToken: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let songs = try await service.getRecentlyPlayedTracks(
+        musicUserToken: musicUserToken,
+        options: pagination)
+      return BridgeResponses.songs(songs)
+    }
+  }
+
+  static func getHeavyRotation(
+    service: HistoryService,
+    musicUserToken: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let items = try await service.getHeavyRotation(
+        musicUserToken: musicUserToken,
+        limit: pagination.limit)
+      return BridgeResponses.recentItems(items)
+    }
+  }
+
+  static func getRecentlyPlayedStations(
+    service: HistoryService,
+    musicUserToken: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let stations = try await service.getRecentlyPlayedStations(
+        musicUserToken: musicUserToken,
+        limit: pagination.limit)
+      return BridgeResponses.stations(stations)
+    }
+  }
+
+  static func getRecentlyAdded(
+    service: HistoryService,
+    musicUserToken: String,
+    options: NSDictionary
+  ) async throws -> [String: Any] {
+    try await AppleMusicBridgeError.rethrow {
+      let pagination = BridgePagination(from: options)
+      let items = try await service.getRecentlyAdded(
+        musicUserToken: musicUserToken,
+        limit: pagination.limit,
+        offset: pagination.offset)
+      return BridgeResponses.recentItems(items)
+    }
+  }
+}