@wwdrew/expo-apple-music 1.0.0

package/expo-module.config.json

@@ -0,0 +1,19 @@
+{
+  "platforms": ["apple", "android", "web"],
+  "apple": {
+    "modules": ["ExpoAppleMusicModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.applemusic.ExpoAppleMusicModule"],
+    "gradleAarProjects": [
+      {
+        "name": "musickit-auth",
+        "aarFilePath": "android/libs/musickitauth-release-1.1.2.aar"
+      },
+      {
+        "name": "musickit-playback",
+        "aarFilePath": "android/libs/mediaplayback-release-1.1.1.aar"
+      }
+    ]
+  }
+}

package/ios/AppleMusicBridgeError.swift

@@ -0,0 +1,60 @@
+// AppleMusicBridgeError.swift
+// Map native errors to Expo bridge Exception codes.
+
+import ExpoModulesCore
+
+@available(iOS 16.0, *)
+enum AppleMusicBridgeError {
+  /// Maps thrown errors to Expo `Exception` codes for async bridge methods.
+  static func rethrow<T>(_ operation: () async throws -> T) async throws -> T {
+    do {
+      return try await operation()
+    } catch let exception as Exception {
+      throw exception
+    } catch {
+      throw exception(from: error)
+    }
+  }
+
+  static func exception(from error: Error) -> Exception {
+    if let rest = error as? AppleMusicRestClient.RestError {
+      let code = rest.bridgeCode
+      return Exception(
+        name: code,
+        description: rest.errorDescription ?? "Apple Music error",
+        code: code
+      )
+    }
+
+    if let catalog = error as? CatalogService.CatalogServiceError {
+      switch catalog {
+      case .configurationRequired(let message):
+        return Exception(
+          name: AppleMusicErrorCodes.permissionDenied,
+          description: message,
+          code: AppleMusicErrorCodes.permissionDenied
+        )
+      case .notFound, .unknownResourceType:
+        let message = catalog.errorDescription ?? "Apple Music error"
+        return Exception(name: AppleMusicErrorCodes.error, description: message, code: AppleMusicErrorCodes.error)
+      }
+    }
+
+    if let subscription = error as? SubscriptionService.SubscriptionError {
+      return Exception(
+        name: subscription.code,
+        description: subscription.errorDescription ?? "Apple Music error",
+        code: subscription.code
+      )
+    }
+
+    let message = error.localizedDescription
+    let code =
+      message.localizedCaseInsensitiveContains("403")
+        || message.localizedCaseInsensitiveContains("authorization required")
+        || message.localizedCaseInsensitiveContains("subscription needed")
+      ? AppleMusicErrorCodes.permissionDenied
+      : AppleMusicErrorCodes.error
+    return Exception(name: code, description: message, code: code)
+  }
+}

package/ios/AppleMusicErrorCodes.swift

@@ -0,0 +1,11 @@
+// AppleMusicErrorCodes.swift
+// Bridge rejection codes — keep in sync with src/constants/apple-music-error-codes.ts and docs/ERROR_CODES.md.
+
+import Foundation
+
+@available(iOS 16.0, *)
+enum AppleMusicErrorCodes {
+  static let error = "ERROR"
+  static let permissionDenied = "permissionDenied"
+  static let playbackError = "PLAYBACK_ERROR"
+}

package/ios/AppleMusicRestClient.swift

@@ -0,0 +1,213 @@
+// AppleMusicRestClient.swift
+// Authenticated requests to api.music.apple.com (URLSession + stored tokens, or MusicDataRequest).
+
+import Foundation
+import MusicKit
+
+@available(iOS 16.0, *)
+enum AppleMusicHttpMethod: String {
+  case get = "GET"
+  case post = "POST"
+  case put = "PUT"
+  case delete = "DELETE"
+}
+
+@available(iOS 16.0, *)
+enum AppleMusicRestClient {
+
+  enum RestError: LocalizedError {
+    case invalidURL
+    case invalidResponse
+    case permissionDenied(String)
+    case apiError(String)
+
+    var errorDescription: String? {
+      switch self {
+      case .invalidURL: return "Invalid Apple Music API URL"
+      case .invalidResponse: return "Invalid Apple Music API response"
+      case .permissionDenied(let message): return message
+      case .apiError(let message): return message
+      }
+    }
+
+    var bridgeCode: String {
+      switch self {
+      case .permissionDenied:
+        return AppleMusicErrorCodes.permissionDenied
+      case .invalidURL, .invalidResponse, .apiError:
+        return AppleMusicErrorCodes.error
+      }
+    }
+  }
+
+  static func request(
+    method: AppleMusicHttpMethod,
+    path: String,
+    musicUserToken: String? = nil,
+    query: [String: String] = [:],
+    body: [String: Any]? = nil
+  ) async throws -> [String: Any] {
+    let session = AuthenticatedSession.current
+    if path.hasPrefix("/v1/me/") {
+      guard let musicUserToken, !musicUserToken.isEmpty else {
+        throw RestError.apiError("Apple Music REST requires a music user token")
+      }
+      return try await requestViaUrlSession(
+        session: session,
+        method: method,
+        path: path,
+        musicUserToken: musicUserToken,
+        query: query,
+        body: body)
+    }
+    if method == .get, session.prefersStoredDeveloperTokenForGet {
+      return try await requestViaUrlSession(
+        session: session,
+        method: method,
+        path: path,
+        musicUserToken: nil,
+        query: query,
+        body: body)
+    }
+    if method == .get, session.canUseMusicKitAutoTokenForGet {
+      return try await getViaMusicDataRequest(path: path, query: query)
+    }
+    return try await requestViaUrlSession(
+      session: session,
+      method: method,
+      path: path,
+      musicUserToken: musicUserToken,
+      query: query,
+      body: body)
+  }
+
+  static func get(
+    path: String,
+    musicUserToken: String? = nil,
+    query: [String: String] = [:]
+  ) async throws -> [String: Any] {
+    try await request(method: .get, path: path, musicUserToken: musicUserToken, query: query)
+  }
+
+  static func getDataArray(
+    path: String,
+    musicUserToken: String? = nil,
+    query: [String: String] = [:]
+  ) async throws -> [[String: Any]] {
+    let json = try await get(path: path, musicUserToken: musicUserToken, query: query)
+    return try parseDataArray(from: json)
+  }
+
+  /// Top-level list responses must include a `data` array (may be empty).
+  static func parseDataArray(from json: [String: Any], key: String = "data") throws -> [[String: Any]] {
+    guard json.keys.contains(key) else {
+      throw RestError.apiError("Apple Music API response missing \"\(key)\"")
+    }
+    if json[key] is NSNull {
+      return []
+    }
+    guard let data = json[key] as? [[String: Any]] else {
+      throw RestError.apiError("Apple Music API response \"\(key)\" is not an array")
+    }
+    return data
+  }
+
+  private static func getViaMusicDataRequest(
+    path: String,
+    query: [String: String]
+  ) async throws -> [String: Any] {
+    guard var components = URLComponents(string: "https://api.music.apple.com\(path)") else {
+      throw RestError.invalidURL
+    }
+    if !query.isEmpty {
+      components.queryItems = query.map { URLQueryItem(name: $0.key, value: $0.value) }
+    }
+    guard let url = components.url else {
+      throw RestError.invalidURL
+    }
+
+    let urlRequest = URLRequest(url: url)
+    let dataRequest = MusicDataRequest(urlRequest: urlRequest)
+    let response = try await dataRequest.response()
+    return try parseResponseData(response.data)
+  }
+
+  private static func requestViaUrlSession(
+    session: AuthenticatedSession,
+    method: AppleMusicHttpMethod,
+    path: String,
+    musicUserToken: String?,
+    query: [String: String],
+    body: [String: Any]?
+  ) async throws -> [String: Any] {
+    guard let developerToken = session.developerToken,
+      !developerToken.isEmpty
+    else {
+      if method == .get {
+        return try await getViaMusicDataRequest(path: path, query: query)
+      }
+      throw RestError.apiError("Apple Music REST requires a stored developer token")
+    }
+
+    let userToken = musicUserToken ?? session.musicUserToken
+    let requiresUserToken = session.pathRequiresMusicUserToken(path)
+
+    if requiresUserToken, userToken == nil || userToken?.isEmpty == true {
+      throw RestError.apiError("Apple Music REST requires a music user token")
+    }
+
+    guard var components = URLComponents(string: "https://api.music.apple.com\(path)") else {
+      throw RestError.invalidURL
+    }
+    if !query.isEmpty {
+      components.queryItems = query.map { URLQueryItem(name: $0.key, value: $0.value) }
+    }
+    guard let url = components.url else {
+      throw RestError.invalidURL
+    }
+
+    var urlRequest = URLRequest(url: url)
+    urlRequest.httpMethod = method.rawValue
+    urlRequest.setValue("Bearer \(developerToken)", forHTTPHeaderField: "Authorization")
+    if let userToken, !userToken.isEmpty {
+      urlRequest.setValue(userToken, forHTTPHeaderField: "Music-User-Token")
+    }
+    if let body {
+      urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
+      urlRequest.httpBody = try JSONSerialization.data(withJSONObject: body)
+    }
+
+    let (data, response) = try await URLSession.shared.data(for: urlRequest)
+    if let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode) {
+      if http.statusCode == 403 {
+        throw RestError.permissionDenied(
+          "Apple Music authorization required or subscription needed (403)"
+        )
+      }
+      if let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+        let errors = json["errors"] as? [[String: Any]],
+        let detail = errors.first?["detail"] as? String
+      {
+        throw RestError.apiError(detail)
+      }
+      throw RestError.apiError("Apple Music API error (\(http.statusCode))")
+    }
+    return try parseResponseData(data)
+  }
+
+  private static func parseResponseData(_ data: Data) throws -> [String: Any] {
+    if data.isEmpty {
+      return [:]
+    }
+    guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+      throw RestError.invalidResponse
+    }
+    if let errors = json["errors"] as? [[String: Any]],
+      let first = errors.first,
+      let detail = first["detail"] as? String
+    {
+      throw RestError.apiError(detail)
+    }
+    return json
+  }
+}

package/ios/AuthenticatedSession.swift

@@ -0,0 +1,64 @@
+// AuthenticatedSession.swift
+// Single view of stored credentials and REST/catalog transport preferences (see docs/AUTH.md).
+
+import Foundation
+
+@available(iOS 16.0, *)
+struct AuthenticatedSession {
+  let developerToken: String?
+  let musicUserToken: String?
+
+  static var current: AuthenticatedSession {
+    AuthenticatedSession(
+      developerToken: MusicKitAuthStorage.getDeveloperToken(),
+      musicUserToken: MusicKitAuthStorage.getMusicUserToken()
+    )
+  }
+
+  var hasDeveloperToken: Bool {
+    guard let developerToken, !developerToken.isEmpty else { return false }
+    return true
+  }
+
+  var hasMusicUserToken: Bool {
+    guard let musicUserToken, !musicUserToken.isEmpty else { return false }
+    return true
+  }
+
+  /// Developer JWT and music user token — required for `/v1/me/` REST and full URLSession auth.
+  var hasRestTokens: Bool {
+    hasDeveloperToken && hasMusicUserToken
+  }
+
+  /// GET may use MusicKit `MusicDataRequest` when stored REST tokens are incomplete.
+  var canUseMusicKitAutoTokenForGet: Bool {
+    !hasRestTokens
+  }
+
+  /// GET with a stored developer JWT uses URLSession + Bearer (see `AppleMusicRestClient`).
+  var prefersStoredDeveloperTokenForGet: Bool {
+    hasDeveloperToken
+  }
+
+  func pathRequiresMusicUserToken(_ path: String) -> Bool {
+    path.hasPrefix("/v1/me/")
+  }
+}
+
+/// In-memory storefront resolved after auth; cleared when tokens change.
+@available(iOS 16.0, *)
+enum AuthenticatedSessionCache {
+  private static var storefrontId: String?
+
+  static func cachedStorefrontId() -> String? {
+    storefrontId
+  }
+
+  static func setStorefrontId(_ id: String) {
+    storefrontId = id
+  }
+
+  static func invalidate() {
+    storefrontId = nil
+  }
+}

package/ios/BridgePagination.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+/// Shared bridge pagination defaults (limit 25, offset 0).
+struct BridgePagination {
+  let limit: Int
+  let offset: Int
+
+  init(from dictionary: NSDictionary) {
+    limit = dictionary["limit"] as? Int ?? 25
+    offset = dictionary["offset"] as? Int ?? 0
+  }
+
+  init(limit: Int, offset: Int) {
+    self.limit = limit
+    self.offset = offset
+  }
+}

package/ios/BridgeResponses.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+/// Standard bridge response envelopes (keys match Android and TypeScript).
+enum BridgeResponses {
+  static func storefront(id: String) -> [String: Any] {
+    ["id": id]
+  }
+
+  static func catalogSearch(_ result: CatalogService.SearchResult) -> [String: Any] {
+    [
+      "songs": result.songs,
+      "albums": result.albums,
+      "artists": result.artists,
+      "playlists": result.playlists,
+      "stations": result.stations,
+      "musicVideos": result.musicVideos,
+    ]
+  }
+
+  static func catalogCharts(_ result: CatalogService.ChartsResult) -> [String: Any] {
+    [
+      "songs": result.songs,
+      "albums": result.albums,
+      "playlists": result.playlists,
+      "musicVideos": result.musicVideos,
+    ]
+  }
+
+  static func songs(_ items: [[String: Any]]) -> [String: Any] {
+    ["songs": items]
+  }
+
+  static func albums(_ items: [[String: Any]]) -> [String: Any] {
+    ["albums": items]
+  }
+
+  static func artists(_ items: [[String: Any]]) -> [String: Any] {
+    ["artists": items]
+  }
+
+  static func playlists(_ items: [[String: Any]]) -> [String: Any] {
+    ["playlists": items]
+  }
+
+  static func musicVideos(_ items: [[String: Any]]) -> [String: Any] {
+    ["musicVideos": items]
+  }
+
+  static func librarySearch(_ result: LibraryService.LibrarySearchResult) -> [String: Any] {
+    [
+      "songs": result.songs,
+      "albums": result.albums,
+      "artists": result.artists,
+      "playlists": result.playlists,
+      "musicVideos": result.musicVideos,
+    ]
+  }
+
+  static func stations(_ items: [[String: Any]]) -> [String: Any] {
+    ["stations": items]
+  }
+
+  static func recentlyPlayedResources(_ items: [[String: Any]]) -> [String: Any] {
+    ["recentlyPlayedItems": items]
+  }
+
+  static func recentItems(_ items: [[String: Any]]) -> [String: Any] {
+    ["items": items]
+  }
+
+  static func recommendations(_ items: [[String: Any]]) -> [String: Any] {
+    ["recommendations": items]
+  }
+
+  static func replaySummaries(_ items: [[String: Any]]) -> [String: Any] {
+    ["summaries": items]
+  }
+
+  static func configurePlayer(mixWithOthers: Bool) -> [String: Any] {
+    ["mixWithOthers": mixWithOthers]
+  }
+}

package/ios/CatalogSearchStore.swift

@@ -0,0 +1,13 @@
+// CatalogSearchStore.swift
+// Catalog search transport seam — native MusicKit vs REST (developer JWT).
+
+import Foundation
+
+@available(iOS 16.0, *)
+protocol CatalogSearchStore {
+  func search(
+    term: String,
+    types: [String],
+    options: CatalogService.SearchOptions
+  ) async throws -> CatalogService.SearchResult
+}

package/ios/CatalogSearchStoreFactory.swift

@@ -0,0 +1,31 @@
+// CatalogSearchStoreFactory.swift
+// Native MusicKit search first; REST fallback only when auto-token fails and a developer JWT is stored.
+
+import Foundation
+
+@available(iOS 16.0, *)
+enum CatalogSearchStoreFactory {
+
+  static func search(
+    term: String,
+    types: [String],
+    options: CatalogService.SearchOptions
+  ) async throws -> CatalogService.SearchResult {
+    do {
+      return try await MusicKitCatalogSearchStore().search(
+        term: term, types: types, options: options)
+    } catch {
+      if MusicKitCatalogSearchStore.isClientNotRegistered(error),
+        AuthenticatedSession.current.hasDeveloperToken
+      {
+        return try await RestCatalogSearchStore().search(
+          term: term, types: types, options: options)
+      }
+      if MusicKitCatalogSearchStore.isClientNotRegistered(error) {
+        throw CatalogService.CatalogServiceError.configurationRequired(
+          MusicKitCatalogSearchStore.missingDeveloperTokenMessage)
+      }
+      throw error
+    }
+  }
+}