@wwdrew/expo-apple-music 1.0.0 → 1.1.0

package/README.md

@@ -4,13 +4,32 @@ Cross-platform Apple Music API for **Expo** (SDK 56 · iOS 16.4+ · Android · W
 
 Inspired by [`@lomray/react-native-apple-music`](https://github.com/Lomray-Software/react-native-apple-music) — not a drop-in replacement. See [ATTRIBUTION.md](./ATTRIBUTION.md).
 
+## Android: Apple's SDK is your responsibility
+
+**If you target Android, you must obtain Apple's MusicKit SDK binaries yourself. This package does not include them, cannot ship them on npm, and there is no way to skip this step.**
+
+Apple's MusicKit for Android is distributed as two proprietary `.aar` files (authentication + playback). They are gated behind an [Apple Developer](https://developer.apple.com/account/) login and **cannot be redistributed** by third-party libraries. `npx expo install @wwdrew/expo-apple-music` alone is **not** enough for Android — prebuild will fail until you:
+
+1. **Download** the [MusicKit SDK for Android](https://developer.apple.com/musickit/) from Apple (Developer account required).
+2. **Store** both `.aar` files in a directory inside **your app repo** (for example `./vendor/apple-musickit-android/` — typically gitignored).
+3. **Configure** the config plugin with `androidMusicKitAarDir` pointing at that directory.
+
+At `npx expo prebuild` for Android, the plugin copies those files into the native build. If the directory is missing or either file is absent, **the build stops with an error**. There is no stub mode, no automatic download, and no fallback.
+
+| File | Purpose |
+| --- | --- |
+| `musickitauth-release-1.1.2.aar` | Apple Music sign-in |
+| `mediaplayback-release-1.1.1.aar` | Playback |
+
+**iOS and web are unaffected** — this requirement applies only to Android native builds. Full setup: **[docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md)**.
+
 ## Install
 
 ```sh
 npx expo install @wwdrew/expo-apple-music
 ```
 
-Add the config plugin and enable **MusicKit** on your App ID in the Apple Developer portal. Full steps: **[docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md)**.
+Add the config plugin and enable **MusicKit** on your App ID in the Apple Developer portal. See **[docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md)** for the full checklist (JWT, iOS entitlements, web origin, etc.).
 
 ```ts
 // app.config.ts
@@ -18,7 +37,11 @@ import expoAppleMusic from '@wwdrew/expo-apple-music/plugin';
 
 export default {
   plugins: [
-    expoAppleMusic({ musicUsageDescription: 'We use Apple Music in this app.' }),
+    expoAppleMusic({
+      musicUsageDescription: 'We use Apple Music in this app.',
+      // Required for Android prebuild — see "Android: Apple's SDK is your responsibility" above
+      androidMusicKitAarDir: './vendor/apple-musickit-android',
+    }),
   ],
 };
 ```
@@ -37,7 +60,7 @@ if (status === AuthStatus.AUTHORIZED && musicUserToken) {
 }
 ```
 
-**Developer JWT:** your app signs and serves it — not included in this package. Local dev: clone the repo and use `npm run dev-token` ([docs/CLI.md](./docs/CLI.md)).
+**Developer JWT:** your app signs and serves it — not included in this package. Local dev: clone the repo and use `yarn dev-token` ([docs/CLI.md](./docs/CLI.md)).
 
 ## Documentation
 
@@ -46,7 +69,7 @@ All guides live in **[docs/](./docs/)** (browse on GitHub):
 | | |
 | --- | --- |
 | **[Getting started](./docs/GETTING_STARTED.md)** | Install → authorize → search → play |
-| **[Building locally](./docs/BUILDING_LOCALLY.md)** | Clone, Android `.aar` libs, example app |
+| **[Building locally](./docs/BUILDING_LOCALLY.md)** | Clone, example app, Android `.aar` setup |
 | **[Auth](./docs/AUTH.md)** | JWT, `AuthStatus`, platform requirements |
 | **[iOS setup](./docs/IOS_SETUP.md)** | Portal, signing, entitlements |
 | **[API coverage](./docs/APPLE_MUSIC_API.md)** | Per-method iOS / Android / web matrix |
@@ -68,11 +91,10 @@ Details: [docs/APPLE_MUSIC_API.md](./docs/APPLE_MUSIC_API.md).
 
 ## Building locally (repo clone)
 
-The **example app** and Android native builds need Apple’s MusicKit Android `.aar` libraries in `android/libs/`. Those binaries are **gitignored** and are **not** in the repository — download them from Apple. Full steps: **[docs/BUILDING_LOCALLY.md](./docs/BUILDING_LOCALLY.md)**.
+Clone this repo to run the example app or contribute. The same Android SDK requirement applies: place Apple's `.aar` files in `example/vendor/apple-musickit-android/` before Android prebuild. See **[docs/BUILDING_LOCALLY.md](./docs/BUILDING_LOCALLY.md)**.
 
 ```sh
-# After placing mediaplayback-release-1.1.1.aar and musickitauth-release-1.1.2.aar in android/libs/
-npm run dev-token -- --write-env example/.env.local
+yarn dev-token -- --write-env example/.env.local
 cd example && npx expo start
 ```
 

package/android/src/main/java/expo/modules/applemusic/ExpoAppleMusicModule.kt

@@ -22,20 +22,24 @@ class ExpoAppleMusicModule : Module() {
   private lateinit var authLauncher: AppContextActivityResultLauncher<MusicKitAuthInput, MusicKitAuthOutput>
   private var playbackObserver: AndroidPlaybackObserver? = null
 
+  @Volatile
+  private var playbackErrorHandlerWired = false
+
   private val moduleScope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
 
   private val reactContext
     get() = requireNotNull(appContext.reactContext) { "React Application Context is null" }
 
   private val playbackController: AndroidPlaybackController
-    get() =
-      AndroidPlaybackController.getInstance(reactContext).also { controller ->
-        if (controller.playbackErrorHandler == null) {
-          controller.playbackErrorHandler = { error, operation ->
-            emitPlaybackError(error, operation)
-          }
-        }
-      }
+    get() = AndroidPlaybackController.getInstance(reactContext)
+
+  private fun wirePlaybackErrorHandlerOnce() {
+    if (playbackErrorHandlerWired) return
+    AndroidPlaybackController.getInstance(reactContext).playbackErrorHandler = { error, operation ->
+      emitPlaybackError(error, operation)
+    }
+    playbackErrorHandlerWired = true
+  }
 
   private val catalogService: AndroidCatalogService
     get() = AndroidCatalogService(reactContext)
@@ -72,6 +76,7 @@ class ExpoAppleMusicModule : Module() {
     )
 
     OnStartObserving {
+      wirePlaybackErrorHandlerOnce()
       val observer = AndroidPlaybackObserver(reactContext)
       observer.delegate =
         object : AndroidPlaybackObserverDelegate {
@@ -107,6 +112,7 @@ class ExpoAppleMusicModule : Module() {
             appContext.throwingActivity
           },
         )
+      wirePlaybackErrorHandlerOnce()
     }
 
     registerAuthBridge(

package/ios/ExpoAppleMusicModule.swift

@@ -2,468 +2,22 @@ import ExpoModulesCore
 
 @available(iOS 16.0, *)
 public class ExpoAppleMusicModule: Module {
-  private let playbackController = PlaybackController.shared
-  private let subscriptionService = SubscriptionService()
-  private let catalogService = CatalogService()
-  private lazy var queueService = QueueService(
+  let playbackController = PlaybackController.shared
+  let subscriptionService = SubscriptionService()
+  let catalogService = CatalogService()
+  lazy var queueService = QueueService(
     playbackController: playbackController,
     catalogService: catalogService
   )
-  private lazy var libraryService = LibraryService()
-  private lazy var historyService = HistoryService()
-  private lazy var ratingsService = RatingsService()
-  private lazy var libraryMutationsService = LibraryMutationsService()
-  private lazy var recommendationsService = RecommendationsService()
+  lazy var libraryService = LibraryService()
+  lazy var historyService = HistoryService()
+  lazy var ratingsService = RatingsService()
+  lazy var libraryMutationsService = LibraryMutationsService()
+  lazy var recommendationsService = RecommendationsService()
 
-  private var playbackObserver: PlaybackObserver?
+  var playbackObserver: PlaybackObserver?
 
-  public func definition() -> ModuleDefinition {
-    Name("ExpoAppleMusic")
-
-      Events(
-        "onPlaybackStateChange",
-        "onCurrentSongChange",
-        "onPlaybackTimeUpdate",
-        "onPlaybackError"
-      )
-
-      OnStartObserving {
-        let observer = PlaybackObserver(playbackController: self.playbackController)
-        observer.delegate = self
-        observer.startObserving()
-        self.playbackObserver = observer
-      }
-
-      OnStopObserving {
-        self.playbackObserver?.stopObserving()
-        self.playbackObserver = nil
-      }
-
-      // MARK: - Auth
-
-      AsyncFunction("setDeveloperToken") { (token: String) in
-        MusicKitAuthStorage.saveDeveloperToken(token)
-      }
-
-      AsyncFunction("authorization") { (developerToken: String?, _ startScreenMessage: String?, _ hideStartScreen: Bool?) -> [String: Any?] in
-        if let token = developerToken, !token.isEmpty {
-          MusicKitAuthStorage.saveDeveloperToken(token)
-        }
-        let status = await self.subscriptionService.requestAuthorization()
-        var musicUserToken: String? = nil
-        if status == .authorized, let token = developerToken, !token.isEmpty {
-          musicUserToken = await self.subscriptionService.fetchMusicUserToken(developerToken: token)
-        }
-        return ["status": status.rawValue, "musicUserToken": musicUserToken]
-      }
-
-      AsyncFunction("checkSubscription") { (musicUserToken: String) -> [String: Any] in
-        do {
-          let details = try await self.subscriptionService.checkSubscription()
-          return details.toDictionary()
-        } catch {
-          if let subError = SubscriptionService.wrapSubscriptionError(error) {
-            throw Exception(
-              name: subError.code,
-              description: subError.message,
-              code: subError.code
-            )
-          }
-          throw AppleMusicBridgeError.exception(from: error)
-        }
-      }
-
-      AsyncFunction("getStorefront") { (musicUserToken: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          let id = try await StorefrontService.getStorefrontId(musicUserToken: musicUserToken)
-          return BridgeResponses.storefront(id: id)
-        }
-      }
-
-      // MARK: - Catalog
-
-      AsyncFunction("catalogSearch") { (term: String, types: [String], options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeCatalog.catalogSearch(
-          service: self.catalogService,
-          term: term,
-          types: types,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getCatalogSong") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getSong(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogAlbum") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getAlbum(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogArtist") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getArtist(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogPlaylist") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getPlaylist(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogStation") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getStation(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogMusicVideo") { (id: String) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.catalogService.getMusicVideo(id: id)
-        }
-      }
-
-      AsyncFunction("getCatalogAlbumTracks") { (albumId: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeCatalog.getCatalogAlbumTracks(
-          service: self.catalogService,
-          albumId: albumId,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getCatalogArtistAlbums") { (artistId: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeCatalog.getCatalogArtistAlbums(
-          service: self.catalogService,
-          artistId: artistId,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getCatalogPlaylistTracks") { (playlistId: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeCatalog.getCatalogPlaylistTracks(
-          service: self.catalogService,
-          playlistId: playlistId,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getCatalogCharts") { (types: [String], options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeCatalog.getCatalogCharts(
-          service: self.catalogService,
-          types: types,
-          options: options
-        )
-      }
-
-      AsyncFunction("getCatalogResources") { (type: String, ids: [String]) -> [String: Any] in
-        try await ExpoBridgeCatalog.getCatalogResources(
-          service: self.catalogService,
-          type: type,
-          ids: ids
-        )
-      }
-
-      // MARK: - Library
-
-      AsyncFunction("getUserPlaylists") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getUserPlaylists(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getLibrarySongs") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getLibrarySongs(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getPlaylistSongs") { (musicUserToken: String, playlistId: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getPlaylistSongs(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          playlistId: playlistId
-        )
-      }
-
-      AsyncFunction("getLibraryArtists") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getLibraryArtists(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getLibraryAlbums") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getLibraryAlbums(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getLibraryMusicVideos") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.getLibraryMusicVideos(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("librarySearch") { (musicUserToken: String, term: String, types: [String], options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeLibrary.librarySearch(
-          service: self.libraryService,
-          musicUserToken: musicUserToken,
-          term: term,
-          types: types,
-          options: options as NSDictionary
-        )
-      }
-
-      // MARK: - History
-
-      AsyncFunction("getRecentlyPlayedResources") { (musicUserToken: String) -> [String: Any] in
-        try await ExpoBridgeHistory.getRecentlyPlayedResources(
-          service: self.historyService,
-          musicUserToken: musicUserToken)
-      }
-
-      AsyncFunction("getRecentlyPlayedTracks") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeHistory.getRecentlyPlayedTracks(
-          service: self.historyService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getHeavyRotation") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeHistory.getHeavyRotation(
-          service: self.historyService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getRecentlyPlayedStations") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeHistory.getRecentlyPlayedStations(
-          service: self.historyService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      AsyncFunction("getRecentlyAdded") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await ExpoBridgeHistory.getRecentlyAdded(
-          service: self.historyService,
-          musicUserToken: musicUserToken,
-          options: options as NSDictionary
-        )
-      }
-
-      // MARK: - Player
-
-      AsyncFunction("setPlaybackQueue") { (itemId: String, type: String) -> String in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.queueService.setQueue(itemId: itemId, type: type)
-          return "Track(s) added to queue"
-        }
-      }
-
-      AsyncFunction("configurePlayer") { (mixWithOthers: Bool) -> [String: Any] in
-        try self.playbackController.configureAudioSession(mixWithOthers: mixWithOthers)
-        return BridgeResponses.configurePlayer(mixWithOthers: mixWithOthers)
-      }
-
-      Function("play") {
-        Task {
-          do {
-            try await self.playbackController.play()
-          } catch {
-            self.emitPlaybackError(error, operation: "play")
-          }
-        }
-      }
-
-      Function("pause") {
-        self.playbackController.pause()
-      }
-
-      Function("skipToNextEntry") {
-        Task {
-          do {
-            try await self.playbackController.skipToNext()
-          } catch {
-            self.emitPlaybackError(error, operation: "skipToNext")
-          }
-        }
-      }
-
-      Function("skipToPreviousEntry") {
-        Task {
-          do {
-            try await self.playbackController.skipToPrevious()
-          } catch {
-            self.emitPlaybackError(error, operation: "skipToPrevious")
-          }
-        }
-      }
-
-      Function("restartCurrentEntry") {
-        Task { @MainActor in
-          self.playbackController.restartCurrentEntry()
-          self.playbackTimeDidUpdate(0)
-        }
-      }
-
-      Function("seekToTime") { (time: Double) in
-        Task { @MainActor in
-          self.playbackController.seek(to: time)
-          self.playbackTimeDidUpdate(time)
-        }
-      }
-
-      Function("togglePlayerState") {
-        Task {
-          do {
-            try await self.playbackController.togglePlayback()
-          } catch {
-            self.emitPlaybackError(error, operation: "togglePlayback")
-          }
-        }
-      }
-
-      AsyncFunction("getCurrentState") { () -> [String: Any] in
-        let state = self.playbackController.state
-        let songInfo = await self.playbackController.fetchCurrentSongInfo()
-
-        var result: [String: Any] = [
-          "playbackRate": state.playbackRate,
-          "playbackStatus": MusicItemMapper.describePlaybackStatus(state.playbackStatus),
-          "playbackTime": self.playbackController.playbackTime,
-        ]
-        if let songInfo = songInfo {
-          result["currentSong"] = songInfo
-        }
-        return result
-      }
-
-      AsyncFunction("playLibrarySong") { (musicUserToken: String, songId: String) -> String in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.queueService.playLibrarySong(musicUserToken: musicUserToken, songId: songId)
-          return "Library song added to queue"
-        }
-      }
-
-      AsyncFunction("playLibraryPlaylist") { (musicUserToken: String, playlistId: String, startingAt: Int) -> String in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.queueService.playLibraryPlaylist(
-            musicUserToken: musicUserToken,
-            playlistId: playlistId,
-            startingAt: startingAt
-          )
-          return "Library playlist added to queue"
-        }
-      }
-
-      // MARK: - Ratings
-
-      AsyncFunction("getRating") { (musicUserToken: String, resourceType: String, id: String) -> [String: Any]? in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.ratingsService.getRating(
-            musicUserToken: musicUserToken, resourceType: resourceType, id: id)
-        }
-      }
-
-      AsyncFunction("setRating") { (musicUserToken: String, resourceType: String, id: String, value: Int) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.ratingsService.setRating(
-            musicUserToken: musicUserToken, resourceType: resourceType, id: id, value: value)
-        }
-      }
-
-      AsyncFunction("clearRating") { (musicUserToken: String, resourceType: String, id: String) -> Void in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.ratingsService.clearRating(
-            musicUserToken: musicUserToken, resourceType: resourceType, id: id)
-        }
-      }
-
-      AsyncFunction("addToFavorites") { (musicUserToken: String, resourceIds: [String: [String]]) -> Void in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.ratingsService.addToFavorites(
-            musicUserToken: musicUserToken, resourceIds: resourceIds)
-        }
-      }
-
-      AsyncFunction("removeFromFavorites") { (musicUserToken: String, resourceIds: [String: [String]]) -> Void in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.ratingsService.removeFromFavorites(
-            musicUserToken: musicUserToken, resourceIds: resourceIds)
-        }
-      }
-
-      // MARK: - Library mutations
-
-      AsyncFunction("addToLibrary") { (musicUserToken: String, resourceIds: [String: [String]]) -> Void in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.libraryMutationsService.addToLibrary(
-            musicUserToken: musicUserToken, resourceIds: resourceIds)
-        }
-      }
-
-      AsyncFunction("createLibraryPlaylist") { (musicUserToken: String, options: [String: Any]) -> [String: Any] in
-        try await AppleMusicBridgeError.rethrow {
-          let name = options["name"] as? String ?? ""
-          let description = options["description"] as? String
-          let isPublic = options["isPublic"] as? Bool ?? false
-          let tracks = options["tracks"] as? [[String: String]]
-          return try await self.libraryMutationsService.createPlaylist(
-            musicUserToken: musicUserToken,
-            name: name,
-            description: description,
-            isPublic: isPublic,
-            tracks: tracks
-          )
-        }
-      }
-
-      AsyncFunction("addTracksToLibraryPlaylist") { (musicUserToken: String, playlistId: String, tracks: [[String: String]]) -> Void in
-        try await AppleMusicBridgeError.rethrow {
-          try await self.libraryMutationsService.addTracksToPlaylist(
-            musicUserToken: musicUserToken,
-            playlistId: playlistId,
-            tracks: tracks
-          )
-        }
-      }
-
-      // MARK: - Recommendations
-
-      AsyncFunction("getRecommendations") { (musicUserToken: String, ids: [String]?) -> [String: Any] in
-        try await ExpoBridgeRecommendations.getRecommendations(
-          service: self.recommendationsService,
-          musicUserToken: musicUserToken,
-          ids: ids
-        )
-      }
-
-      AsyncFunction("getReplay") { (musicUserToken: String, year: Int?) -> [String: Any] in
-        try await ExpoBridgeRecommendations.getReplay(
-          service: self.recommendationsService,
-          musicUserToken: musicUserToken,
-          year: year
-        )
-      }
-  }
-
-  private func emitPlaybackError(_ error: Error, operation: String) {
+  func emitPlaybackError(_ error: Error, operation: String) {
     let nsError = error as NSError
     sendEvent(
       "onPlaybackError",