@wwdrew/expo-apple-music 1.0.0

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

@@ -0,0 +1,78 @@
+package expo.modules.applemusic
+
+import android.content.Context
+
+internal class AndroidQueueService(
+  context: Context,
+  private val playback: AndroidPlaybackController,
+  private val library: LibraryRestClient,
+) {
+  constructor(context: Context, playback: AndroidPlaybackController) : this(
+    context,
+    playback,
+    AppleMusicRestStack.create(context).library,
+  )
+
+  enum class MediaType(val raw: String) {
+    SONG("song"),
+    ALBUM("album"),
+    PLAYLIST("playlist"),
+    STATION("station"),
+    ;
+
+    companion object {
+      fun from(raw: String): MediaType? = entries.find { it.raw == raw }
+    }
+  }
+
+  suspend fun setQueue(itemId: String, type: String) {
+    val mediaType =
+      MediaType.from(type) ?: throw AppleMusicErrors.unknownMediaType(type)
+    val isLibrary = LibraryIds.isLibraryId(itemId)
+
+    if (isLibrary) {
+      throw AppleMusicErrors.apiError(
+        "Library queue requires a music user token. Use Player.playLibrarySong or playLibraryPlaylist.",
+      )
+    } else {
+      setCatalogQueue(itemId, mediaType)
+    }
+  }
+
+  private suspend fun setCatalogQueue(itemId: String, type: MediaType) {
+    val provider =
+      when (type) {
+        MediaType.SONG -> playback.buildSongProvider(itemId)
+        MediaType.ALBUM -> playback.buildAlbumProvider(itemId)
+        MediaType.PLAYLIST -> playback.buildPlaylistProvider(itemId)
+        MediaType.STATION ->
+          throw AppleMusicErrors.apiError("Station playback is not supported on Android yet.")
+      }
+    playback.clearSongCache()
+    playback.prepareQueue(provider)
+  }
+
+  suspend fun playLibrarySong(musicUserToken: String, songId: String) {
+    val catalogId = library.resolveCatalogPlaybackId(musicUserToken, songId, "song")
+    playback.clearSongCache()
+    playback.prepareQueue(playback.buildSongProvider(catalogId), musicUserToken)
+  }
+
+  suspend fun playLibraryPlaylist(musicUserToken: String, playlistId: String, startingAt: Int) {
+    val catalogIds = library.resolveLibrarySongCatalogIds(musicUserToken, playlistId)
+    if (catalogIds.isEmpty()) {
+      throw AppleMusicErrors.noSongsInPlaylist()
+    }
+    val startIndex =
+      when {
+        startingAt == -1 -> 0
+        startingAt in catalogIds.indices -> startingAt
+        else -> 0
+      }
+    playback.clearSongCache()
+    playback.prepareQueue(
+      playback.buildSongProvider(*catalogIds.toTypedArray(), startIndex = startIndex),
+      musicUserToken,
+    )
+  }
+}

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

@@ -0,0 +1,27 @@
+package expo.modules.applemusic
+
+import android.content.Context
+
+internal class AndroidRatingsService(
+  private val ratings: RatingsRestClient,
+) {
+  constructor(context: Context) : this(AppleMusicRestStack.create(context).ratings)
+
+  suspend fun getRating(musicUserToken: String, resourceType: String, id: String): Map<String, Any?>? =
+    ratings.getRating(musicUserToken, resourceType, id)
+
+  suspend fun setRating(musicUserToken: String, resourceType: String, id: String, value: Int): Map<String, Any?> =
+    ratings.setRating(musicUserToken, resourceType, id, value)
+
+  suspend fun clearRating(musicUserToken: String, resourceType: String, id: String) {
+    ratings.clearRating(musicUserToken, resourceType, id)
+  }
+
+  suspend fun addToFavorites(musicUserToken: String, resourceIds: Map<String, List<String>>) {
+    ratings.addToFavorites(musicUserToken, resourceIds)
+  }
+
+  suspend fun removeFromFavorites(musicUserToken: String, resourceIds: Map<String, List<String>>) {
+    ratings.removeFromFavorites(musicUserToken, resourceIds)
+  }
+}

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

@@ -0,0 +1,15 @@
+package expo.modules.applemusic
+
+import android.content.Context
+
+internal class AndroidRecommendationsService(
+  private val recommendations: RecommendationsRestClient,
+) {
+  constructor(context: Context) : this(AppleMusicRestStack.create(context).recommendations)
+
+  suspend fun getRecommendations(musicUserToken: String, ids: List<String>?): List<Map<String, Any?>> =
+    recommendations.getRecommendations(musicUserToken, ids)
+
+  suspend fun getReplay(musicUserToken: String, year: Int?): List<Map<String, Any?>> =
+    recommendations.getReplay(musicUserToken, year)
+}

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

@@ -0,0 +1,24 @@
+package expo.modules.applemusic
+
+import android.content.Context
+
+/**
+ * Approximates iOS [MusicSubscription] fields — there is no equivalent on Android.
+ */
+internal class AndroidSubscriptionService(
+  private val library: LibraryRestClient,
+) {
+  constructor(context: Context) : this(AppleMusicRestStack.create(context).library)
+
+  suspend fun checkSubscription(musicUserToken: String): Map<String, Any?> {
+    val libraryOk = library.probeLibraryAccess(musicUserToken)
+    val canPlay = libraryOk
+
+    return mapOf(
+      "canPlayCatalogContent" to canPlay,
+      "canBecomeSubscriber" to false,
+      "hasCloudLibraryEnabled" to libraryOk,
+      "isMusicCatalogSubscriptionEligible" to false,
+    )
+  }
+}

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

@@ -0,0 +1,13 @@
+package expo.modules.applemusic
+
+/**
+ * Bridge rejection codes — keep in sync with [src/constants/apple-music-error-codes.ts]
+ * and [docs/ERROR_CODES.md].
+ */
+internal object AppleMusicErrorCodes {
+  const val ERROR = "ERROR"
+  const val PERMISSION_DENIED = "permissionDenied"
+  const val MISSING_DEVELOPER_TOKEN = "MISSING_DEVELOPER_TOKEN"
+  const val MISSING_MUSIC_USER_TOKEN = "MISSING_MUSIC_USER_TOKEN"
+  const val PLAYBACK_ERROR = "PLAYBACK_ERROR"
+}

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

@@ -0,0 +1,46 @@
+package expo.modules.applemusic
+
+import expo.modules.kotlin.exception.CodedException
+
+internal object AppleMusicErrors {
+  fun missingMusicUserToken(): CodedException =
+    CodedException(
+      AppleMusicErrorCodes.MISSING_MUSIC_USER_TOKEN,
+      "Apple Music music user token is required. Call Auth.authorize(developerToken) first, then pass the token from AuthorizeResult on user-scoped APIs (or queue playback after authorize on Android).",
+      null,
+    )
+
+  fun missingTokens(): CodedException =
+    CodedException(
+      AppleMusicErrorCodes.PERMISSION_DENIED,
+      "Apple Music authorization required. Call Auth.authorize() first.",
+      null,
+    )
+
+  fun permissionDenied(): CodedException =
+    CodedException(
+      AppleMusicErrorCodes.PERMISSION_DENIED,
+      "Apple Music authorization required or subscription needed (403)",
+      null,
+    )
+
+  fun apiError(message: String, code: String = AppleMusicErrorCodes.ERROR): CodedException =
+    CodedException(code, message, null)
+
+  fun playlistNotFound(): CodedException =
+    CodedException(AppleMusicErrorCodes.ERROR, "Playlist not found in library", null)
+
+  fun itemNotFound(item: String, inLibrary: Boolean): CodedException {
+    val source = if (inLibrary) "library" else "catalog"
+    return CodedException(AppleMusicErrorCodes.ERROR, "$item not found in $source", null)
+  }
+
+  fun unknownMediaType(type: String): CodedException =
+    CodedException(AppleMusicErrorCodes.ERROR, "Unknown media type: $type", null)
+
+  fun unsupportedLibraryType(type: String): CodedException =
+    CodedException(AppleMusicErrorCodes.ERROR, "Unsupported library media type: $type", null)
+
+  fun noSongsInPlaylist(): CodedException =
+    CodedException(AppleMusicErrorCodes.ERROR, "No songs in playlist", null)
+}

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

@@ -0,0 +1,8 @@
+package expo.modules.applemusic
+
+internal enum class AppleMusicHttpMethod {
+  GET,
+  POST,
+  PUT,
+  DELETE,
+}

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

@@ -0,0 +1,258 @@
+package expo.modules.applemusic
+
+import org.json.JSONObject
+
+/**
+ * Maps Apple Music API JSON resources to bridge dictionaries matching [ios/MusicItemMapper.swift].
+ */
+internal object AppleMusicJsonMapper {
+  fun mapSong(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val id = catalogPlaybackId(resource) ?: resource.optString("id", "")
+    return mapOf(
+      "id" to id,
+      "title" to attributes.optString("name", ""),
+      "artistName" to attributes.optString("artistName", ""),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+      "duration" to durationMillis(attributes),
+    )
+  }
+
+  fun mapAlbum(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "title" to attributes.optString("name", ""),
+      "artistName" to attributes.optString("artistName", ""),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+      "trackCount" to attributes.optInt("trackCount", 0),
+    )
+  }
+
+  fun mapArtist(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "name" to attributes.optString("name", ""),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+    )
+  }
+
+  fun mapPlaylist(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val trackCount =
+      when {
+        attributes.has("trackCount") -> attributes.optInt("trackCount", 0)
+        else -> 0
+      }
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "name" to attributes.optString("name", ""),
+      "description" to (attributes.optString("description", "").ifEmpty {
+        attributes.optJSONObject("description")?.optString("standard", "") ?: ""
+      }),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+      "trackCount" to trackCount,
+    )
+  }
+
+  fun mapRecentResource(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val apiType = resource.optString("type", "")
+    val itemType =
+      when {
+        apiType.contains("album") -> "album"
+        apiType.contains("playlist") -> "playlist"
+        apiType.contains("station") -> "station"
+        else -> "unknown"
+      }
+    val subtitle =
+      attributes.optString("artistName", "").ifEmpty {
+        attributes.optString("curatorName", "").ifEmpty {
+          attributes.optJSONObject("description")?.optString("standard", "") ?: ""
+        }
+      }
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "title" to attributes.optString("name", ""),
+      "subtitle" to subtitle,
+      "type" to itemType,
+    )
+  }
+
+  fun mapRecentlyPlayed(resource: JSONObject): Map<String, Any?> = mapRecentResource(resource)
+
+  fun mapStation(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "name" to attributes.optString("name", ""),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+    )
+  }
+
+  fun mapMusicVideo(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val id = catalogPlaybackId(resource) ?: resource.optString("id", "")
+    return mapOf<String, Any?>(
+      "id" to id,
+      "title" to attributes.optString("name", ""),
+      "artistName" to attributes.optString("artistName", ""),
+      "artworkUrl" to artworkUrl(attributes.optJSONObject("artwork")),
+      "duration" to durationMillis(attributes),
+    )
+  }
+
+  fun mapPlayerMediaItem(item: com.apple.android.music.playback.model.PlayerMediaItem): Map<String, Any?> =
+    mapOf(
+      "id" to item.subscriptionStoreId.orEmpty().ifEmpty { item.a().orEmpty() },
+      "title" to item.title.orEmpty(),
+      "artistName" to item.artistName.orEmpty(),
+      "artworkUrl" to (item.getArtworkUrl(200, 200) ?: ""),
+      "duration" to (item.duration / 1000).toString(),
+    )
+
+  /** Maps ratings API envelope (`data[0].attributes.value`). */
+  fun mapRating(json: JSONObject): Map<String, Any?>? {
+    val data = json.optJSONArray("data") ?: return null
+    if (data.length() == 0) return null
+    val item = data.getJSONObject(0)
+    val attributes = item.optJSONObject("attributes") ?: return null
+    if (!attributes.has("value")) return null
+    return mapOf(
+      "id" to item.optString("id", ""),
+      "value" to attributes.getInt("value"),
+    )
+  }
+
+  fun mapRecommendation(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val title =
+      attributes.optJSONObject("title")?.optString("stringForDisplay", "").orEmpty()
+    val resourceTypes =
+      attributes.optJSONArray("resourceTypes")?.let { array ->
+        buildList(array.length()) {
+          for (i in 0 until array.length()) {
+            add(array.optString(i))
+          }
+        }
+      } ?: emptyList()
+    val contents = mapRecommendationContents(resource)
+    return mapOf(
+      "id" to resource.optString("id", ""),
+      "title" to title,
+      "resourceTypes" to resourceTypes,
+      "playlists" to contents.playlists,
+      "albums" to contents.albums,
+      "stations" to contents.stations,
+    )
+  }
+
+  fun mapReplaySummary(resource: JSONObject): Map<String, Any?> {
+    val attributes = resource.optJSONObject("attributes") ?: JSONObject()
+    val topSongs = mapRelationshipResources(resource, "top-songs", ::mapSong)
+    val topAlbums = mapRelationshipResources(resource, "top-albums", ::mapAlbum)
+    val topArtists = mapRelationshipResources(resource, "top-artists", ::mapArtist)
+    return buildMap {
+      put("id", resource.optString("id", ""))
+      put("type", resource.optString("type", ""))
+      put("name", attributes.optString("name", ""))
+      put("topSongs", topSongs)
+      put("topAlbums", topAlbums)
+      put("topArtists", topArtists)
+      if (attributes.has("year")) {
+        put("year", attributes.optInt("year"))
+      }
+    }
+  }
+
+  private data class RecommendationContents(
+    val playlists: List<Map<String, Any?>>,
+    val albums: List<Map<String, Any?>>,
+    val stations: List<Map<String, Any?>>,
+  )
+
+  private fun mapRecommendationContents(resource: JSONObject): RecommendationContents {
+    val data =
+      resource
+        .optJSONObject("relationships")
+        ?.optJSONObject("contents")
+        ?.optJSONArray("data")
+        ?: return RecommendationContents(emptyList(), emptyList(), emptyList())
+    val playlists = buildList {
+      for (i in 0 until data.length()) {
+        val item = data.getJSONObject(i)
+        if (item.optString("type", "").contains("playlist")) {
+          add(mapPlaylist(item))
+        }
+      }
+    }
+    val albums = buildList {
+      for (i in 0 until data.length()) {
+        val item = data.getJSONObject(i)
+        if (item.optString("type", "").contains("album")) {
+          add(mapAlbum(item))
+        }
+      }
+    }
+    val stations = buildList {
+      for (i in 0 until data.length()) {
+        val item = data.getJSONObject(i)
+        if (item.optString("type", "").contains("station")) {
+          add(mapStation(item))
+        }
+      }
+    }
+    return RecommendationContents(playlists, albums, stations)
+  }
+
+  private fun mapRelationshipResources(
+    resource: JSONObject,
+    relationshipKey: String,
+    mapper: (JSONObject) -> Map<String, Any?>,
+  ): List<Map<String, Any?>> {
+    val data =
+      resource
+        .optJSONObject("relationships")
+        ?.optJSONObject(relationshipKey)
+        ?.optJSONArray("data")
+        ?: return emptyList()
+    return buildList(data.length()) {
+      for (i in 0 until data.length()) {
+        add(mapper(data.getJSONObject(i)))
+      }
+    }
+  }
+
+  fun describePlaybackStatus(state: Int): String =
+    when (state) {
+      com.apple.android.music.playback.model.PlaybackState.PLAYING -> "playing"
+      com.apple.android.music.playback.model.PlaybackState.PAUSED -> "paused"
+      com.apple.android.music.playback.model.PlaybackState.STOPPED -> "stopped"
+      else -> "unknown"
+    }
+
+  private fun durationMillis(attributes: JSONObject): Long {
+    return when {
+      attributes.has("durationInMillis") -> attributes.optLong("durationInMillis", 0)
+      attributes.has("duration") -> (attributes.optDouble("duration", 0.0) * 1000).toLong()
+      else -> 0L
+    }
+  }
+
+  /** Catalog song id for [CatalogPlaybackQueueItemProvider] (playParams when present). */
+  fun catalogPlaybackId(resource: JSONObject): String? {
+    val playParams = resource.optJSONObject("attributes")?.optJSONObject("playParams") ?: return null
+    return playParams.optString("id", "").takeIf { it.isNotEmpty() }
+      ?: playParams.optString("catalogId", "").takeIf { it.isNotEmpty() }
+  }
+
+  private fun artworkUrl(artwork: JSONObject?, width: Int = 200, height: Int = 200): String {
+    if (artwork == null) return ""
+    val template = artwork.optString("url", "")
+    if (template.isEmpty()) return ""
+    return template
+      .replace("{w}", width.toString())
+      .replace("{h}", height.toString())
+  }
+}

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

@@ -0,0 +1,32 @@
+package expo.modules.applemusic
+
+import android.util.Log
+
+/**
+ * Loads Apple Music playback natives. Must run before [MediaPlayerControllerFactory].
+ * See Apple / community samples for the bytedeco memory properties.
+ */
+internal object AppleMusicNativeLoader {
+  private const val TAG = "ExpoAppleMusic"
+
+  @Volatile
+  private var loaded = false
+
+  fun ensureLoaded() {
+    if (loaded) return
+    synchronized(this) {
+      if (loaded) return
+      try {
+        System.setProperty("org.bytedeco.javacpp.maxphysicalbytes", "0")
+        System.setProperty("org.bytedeco.javacpp.maxbytes", "0")
+        System.loadLibrary("c++_shared")
+        System.loadLibrary("appleMusicSDK")
+        loaded = true
+        Log.i(TAG, "native libraries loaded")
+      } catch (error: UnsatisfiedLinkError) {
+        Log.e(TAG, "failed to load playback natives", error)
+        throw error
+      }
+    }
+  }
+}

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

@@ -0,0 +1,40 @@
+package expo.modules.applemusic
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** Top-level list responses must include a `data` array (may be empty). */
+internal fun requireDataArray(json: JSONObject, key: String = "data"): JSONArray {
+  if (!json.has(key) || json.isNull(key)) {
+    throw AppleMusicErrors.apiError("Apple Music API response missing \"$key\"")
+  }
+  when (val value = json.get(key)) {
+    is JSONArray -> return value
+    JSONObject.NULL -> return JSONArray()
+    else ->
+      throw AppleMusicErrors.apiError("Apple Music API response \"$key\" is not an array")
+  }
+}
+
+/**
+ * Map a `data` array (or optional nested search bucket).
+ * `null` → empty (type omitted from search). Non-array → reject.
+ */
+internal fun mapResourceArray(
+  array: JSONArray?,
+  mapper: (JSONObject) -> Map<String, Any?>,
+): List<Map<String, Any?>> {
+  if (array == null) return emptyList()
+  return buildList(array.length()) {
+    for (i in 0 until array.length()) {
+      add(mapper(array.getJSONObject(i)))
+    }
+  }
+}
+
+/** Parse required top-level `data`, then map resources. */
+internal fun mapTopLevelResourceArray(
+  json: JSONObject,
+  key: String = "data",
+  mapper: (JSONObject) -> Map<String, Any?>,
+): List<Map<String, Any?>> = mapResourceArray(requireDataArray(json, key), mapper)

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

@@ -0,0 +1,12 @@
+package expo.modules.applemusic
+
+internal fun buildIdsQuery(resourceIds: Map<String, List<String>>): Map<String, String> {
+  val query = linkedMapOf<String, String>()
+  resourceIds.forEach { (type, ids) ->
+    val filtered = ids.filter { it.isNotBlank() }
+    if (filtered.isNotEmpty()) {
+      query["ids[$type]"] = filtered.joinToString(",")
+    }
+  }
+  return query
+}

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

@@ -0,0 +1,19 @@
+package expo.modules.applemusic
+
+import android.content.Context
+
+/** Wires shared REST transport + domain clients for Android services. */
+internal class AppleMusicRestStack(context: Context) {
+  val transport: AppleMusicRestTransport = OkHttpAppleMusicRestTransport(context)
+  val storefront: StorefrontRestClient = StorefrontRestClient(transport)
+  val catalog: CatalogRestClient = CatalogRestClient(transport, storefront)
+  val library: LibraryRestClient = LibraryRestClient(transport)
+  val history: HistoryRestClient = HistoryRestClient(transport)
+  val ratings: RatingsRestClient = RatingsRestClient(transport)
+  val libraryMutations: LibraryMutationsRestClient = LibraryMutationsRestClient(transport)
+  val recommendations: RecommendationsRestClient = RecommendationsRestClient(transport)
+
+  companion object {
+    fun create(context: Context): AppleMusicRestStack = AppleMusicRestStack(context)
+  }
+}