react-native-audio-browser 0.1.1 → 0.2.0-next.1

package/android/src/main/java/com/audiobrowser/browser/BrowserUrlResolution.kt

@@ -0,0 +1,300 @@
+package com.audiobrowser.browser
+
+import com.audiobrowser.util.url
+
+import com.audiobrowser.http.RequestConfigBuilder
+import com.margelo.nitro.audiobrowser.ArtworkRequestConfig
+import com.margelo.nitro.audiobrowser.ImageContext
+import com.margelo.nitro.audiobrowser.ImageQueryParams
+import com.margelo.nitro.audiobrowser.ImageSource
+import com.margelo.nitro.audiobrowser.MediaRequestConfig
+import com.margelo.nitro.audiobrowser.MediaTransformParams
+import com.margelo.nitro.audiobrowser.RequestConfig
+import com.margelo.nitro.audiobrowser.Track
+import timber.log.Timber
+
+/**
+ * Outbound URL resolution for media and artwork — the Android analog of iOS
+ * `BrowserManager+URLResolution.swift`. Owns how a Track's `src` / `artwork` becomes a fetchable
+ * request: request layer (shared, incl. its transform) → kind config (media / artwork /
+ * nowPlayingArtwork) → per-Track Resolve, with transform-wins semantics centralised in
+ * [RequestConfigBuilder].
+ */
+
+/**
+ * Builds the media request config for [originalUrl]. Returns null only when neither a request layer
+ * nor a media config is set (the caller then uses the original URL as-is). Mirrors the web stub's
+ * and iOS's `resolveMediaUrl`.
+ */
+suspend fun BrowserManager.resolveMediaUrl(originalUrl: String): MediaRequestConfig? {
+  val mediaConfig = config.media
+  // The request layer counts as present when a static `request` OR a `requestResolver`
+  // is set — a resolver-only consumer still needs its baseUrl/headers/transform
+  // applied to media URLs.
+  val hasRequestLayer = config.request != null || config.requestResolver != null
+  if (mediaConfig == null && !hasRequestLayer) return null
+
+  // Layered: request (shared, incl. its transform) → media. The request layer runs
+  // for media even when no media-specific config is present (so a relative src
+  // still gets baseUrl).
+  val requestConfig = resolvedRequestConfig()
+  var base =
+    RequestConfig(
+      method = null,
+      path = originalUrl,
+      baseUrl = null,
+      headers = null,
+      query = null,
+      body = null,
+      contentType = null,
+      userAgent = null,
+    )
+  requestConfig?.let { base = RequestConfigBuilder.mergeConfig(base, it) }
+  val mediaLayered =
+    if (mediaConfig != null) {
+      RequestConfigBuilder.mergeConfig(base, mediaConfig)
+    } else {
+      MediaRequestConfig(
+        resolve = null,
+        resolveSync = null,
+        transform = null,
+        transformSync = null,
+        method = base.method,
+        path = base.path,
+        baseUrl = base.baseUrl,
+        headers = base.headers,
+        query = base.query,
+        body = base.body,
+        contentType = base.contentType,
+        userAgent = base.userAgent,
+      )
+    }
+  // Final, most-specific layer: media.resolve(track). The cached Track carries any
+  // per-track `request` override (e.g. a strict-UA sentinel); resolve reads it and
+  // returns the winning config. Only look up the track when a resolve callback
+  // exists, to avoid a needless cache lookup (and its miss-log) otherwise — async
+  // OR sync (the old code checked only `resolve`, silently breaking
+  // resolveSync-only consumers).
+  val track =
+    if (mediaConfig?.resolve != null || mediaConfig?.resolveSync != null) {
+      getCachedTrack(originalUrl)
+    } else null
+  return RequestConfigBuilder.applyMediaResolve(mediaLayered, track)
+}
+
+/**
+ * Resolves a Track's artwork into a fetchable [ImageSource]: request layer → artwork config
+ * (per-route overrides global) → per-Track `artwork.resolve` → image query params from
+ * [imageContext] → artwork transform → `{id}` substitution. Mirrors the web stub's and iOS's
+ * `resolveArtworkUrl` flow. Returns null when there is no artwork (or a resolver explicitly
+ * produced none and the track has no artwork URL).
+ */
+suspend fun BrowserManager.resolveArtworkUrl(
+  track: Track,
+  perRouteConfig: ArtworkRequestConfig? = null,
+  imageContext: ImageContext? = null,
+): ImageSource? {
+  val effectiveArtworkConfig = perRouteConfig ?: config.artwork
+  // Treat empty string as null for artwork
+  val trackArtwork = track.artwork?.url?.takeIf { it.isNotEmpty() }
+
+  // If no artwork config and no track.artwork, nothing to transform
+  if (effectiveArtworkConfig == null && trackArtwork == null) return null
+
+  // If no artwork config, just return the original artwork URL as a simple ImageSource
+  if (effectiveArtworkConfig == null) {
+    return trackArtwork?.let { ImageSource(uri = it, method = null, headers = null, body = null) }
+  }
+
+  return try {
+    // Base via the shared request layer (its transform runs for artwork too),
+    // with the track's artwork as the path when present.
+    var mergedConfig =
+      RequestConfig(
+        method = null,
+        path = null,
+        baseUrl = null,
+        headers = null,
+        query = null,
+        body = null,
+        contentType = null,
+        userAgent = null,
+      )
+    resolvedRequestConfig()?.let {
+      mergedConfig = RequestConfigBuilder.mergeConfig(mergedConfig, it, emptyMap())
+    }
+    if (trackArtwork != null) {
+      mergedConfig = mergedConfig.copy(path = trackArtwork)
+    }
+
+    // Per-track resolution — async `resolve` first, then `resolveSync` merged over
+    // it (sync winning) via the tested helper. Matches the web stub.
+    val asyncResolved =
+      effectiveArtworkConfig.resolve?.let {
+        RequestConfigBuilder.awaitAsyncConfig(it.invoke(track))
+      }
+    val syncResolved =
+      effectiveArtworkConfig.resolveSync?.let {
+        RequestConfigBuilder.awaitSyncConfig(it.invoke(track))
+      }
+    val resolvedConfig = RequestConfigBuilder.composeResolved(asyncResolved, syncResolved)
+
+    // A resolver ran but produced nothing AND there's no artwork URL either → no
+    // artwork (matches the web stub; with a track artwork present the static/url
+    // flow continues).
+    if (
+      (effectiveArtworkConfig.resolve != null || effectiveArtworkConfig.resolveSync != null) &&
+        resolvedConfig == null &&
+        trackArtwork == null
+    ) {
+      return null
+    }
+
+    // Artwork config's static fields (not resolve/transform — those run separately).
+    mergedConfig =
+      RequestConfigBuilder.mergeConfig(
+        mergedConfig,
+        RequestConfigBuilder.toRequestConfig(effectiveArtworkConfig),
+      )
+    resolvedConfig?.let { mergedConfig = RequestConfigBuilder.mergeConfig(mergedConfig, it) }
+
+    // Image query params BEFORE transform (so the transform can override them).
+    mergedConfig =
+      applyImageQueryParams(mergedConfig, effectiveArtworkConfig.imageQueryParams, imageContext)
+
+    // Transform (async first, then sync), receiving the image context.
+    var transformedConfig = mergedConfig
+    effectiveArtworkConfig.transform?.let {
+      transformedConfig =
+        RequestConfigBuilder.awaitAsyncConfig(
+          it.invoke(MediaTransformParams(transformedConfig, imageContext))
+        )
+    }
+    effectiveArtworkConfig.transformSync?.let {
+      transformedConfig =
+        RequestConfigBuilder.awaitSyncConfig(
+          it.invoke(MediaTransformParams(transformedConfig, imageContext))
+        )
+    }
+
+    // `{id}` token substitution, only for a non-empty id. Mirrors iOS substituteTrackId.
+    track.id
+      ?.takeIf { it.isNotEmpty() }
+      ?.let { transformedConfig = substituteTrackId(transformedConfig, it) }
+
+    val uri = RequestConfigBuilder.buildUrl(transformedConfig)
+    // If URI is empty, there's no valid artwork path
+    if (uri.isEmpty()) return null
+
+    ImageSource(
+      uri = uri,
+      method = transformedConfig.method,
+      headers =
+        buildHeadersMap(
+          transformedConfig.headers?.toMap(),
+          transformedConfig.userAgent,
+          transformedConfig.contentType,
+        ),
+      body = transformedConfig.body,
+    )
+  } catch (e: Exception) {
+    Timber.e(e, "Failed to transform artwork URL for track: ${track.title}")
+    // On error, return null to clear artwork and avoid broken images
+    null
+  }
+}
+
+/**
+ * Display-time artwork resolution by URI (Media3's BitmapLoader only receives a URI). A registry
+ * hit re-resolves Track-first with the real display-size [imageContext] — never re-transforming an
+ * already-transformed URL. Returns null for unknown URIs; the caller decides the fallback.
+ */
+suspend fun BrowserManager.displayArtworkSource(
+  uri: String,
+  imageContext: ImageContext?,
+): ImageSource? {
+  val entry = artworkResolutions.lookup(uri) ?: return null
+  return resolveArtworkUrl(entry.track, entry.perRouteConfig, imageContext)
+}
+
+/**
+ * Header-only fallback for display-time artwork URIs that cannot be attributed to a Track (registry
+ * eviction, process-death restore): the URI is fetched as-is — never re-transformed — but the
+ * *static* request/artwork headers still apply, so header-authenticated artwork keeps working.
+ * Transforms are deliberately not run (no Track, no trustworthy base config); headers added by a
+ * transform rather than static config are out of reach here, which is the documented limit. Returns
+ * null when there are no headers to add.
+ */
+suspend fun BrowserManager.unattributedArtworkSource(uri: String): ImageSource? {
+  var merged =
+    RequestConfig(
+      method = null,
+      path = null,
+      baseUrl = null,
+      headers = null,
+      query = null,
+      body = null,
+      contentType = null,
+      userAgent = null,
+    )
+  resolvedRequestConfig()?.let {
+    merged = RequestConfigBuilder.mergeConfig(merged, RequestConfigBuilder.toRequestConfig(it))
+  }
+  config.artwork?.let {
+    merged = RequestConfigBuilder.mergeConfig(merged, RequestConfigBuilder.toRequestConfig(it))
+  }
+  val headers = buildHeadersMap(merged.headers?.toMap(), merged.userAgent, merged.contentType)
+  if (headers == null) return null
+  return ImageSource(uri = uri, method = null, headers = headers, body = null)
+}
+
+/** Folds [imageContext] width/height into the query under the configured param names. */
+private fun applyImageQueryParams(
+  config: RequestConfig,
+  imageQueryParams: ImageQueryParams?,
+  imageContext: ImageContext?,
+): RequestConfig {
+  if (imageContext == null || imageQueryParams == null) return config
+  val contextQuery = mutableMapOf<String, String>()
+  imageQueryParams.width?.let { key ->
+    imageContext.width?.let { contextQuery[key] = it.toInt().toString() }
+  }
+  imageQueryParams.height?.let { key ->
+    imageContext.height?.let { contextQuery[key] = it.toInt().toString() }
+  }
+  if (contextQuery.isEmpty()) return config
+  return config.copy(query = (config.query ?: emptyMap()) + contextQuery)
+}
+
+/**
+ * Replaces the `{id}` token with the track id in a request config's path, query values, and header
+ * values. Used so a `nowPlayingArtwork` like `{ path: "/artwork/{id}" }` resolves. Configs without
+ * the token are returned unchanged. Mirrors the iOS `substituteTrackId` helper.
+ */
+private fun substituteTrackId(config: RequestConfig, id: String): RequestConfig {
+  fun sub(s: String?): String? = s?.replace("{id}", id)
+  fun subMap(m: Map<String, String>?): Map<String, String>? =
+    m?.mapValues { (_, value) -> value.replace("{id}", id) }
+  return config.copy(
+    path = sub(config.path),
+    headers = subMap(config.headers),
+    query = subMap(config.query),
+  )
+}
+
+/** Builds a headers map, merging explicit headers with userAgent and contentType. */
+private fun buildHeadersMap(
+  headers: Map<String, String>?,
+  userAgent: String?,
+  contentType: String?,
+): Map<String, String>? {
+  val mergedHeaders = mutableMapOf<String, String>()
+  headers?.let { mergedHeaders.putAll(it) }
+  if (userAgent != null && !mergedHeaders.containsKey("User-Agent")) {
+    mergedHeaders["User-Agent"] = userAgent
+  }
+  if (contentType != null && !mergedHeaders.containsKey("Content-Type")) {
+    mergedHeaders["Content-Type"] = contentType
+  }
+  return mergedHeaders.ifEmpty { null }
+}

package/android/src/main/java/com/audiobrowser/browser/JsonArtwork.kt

@@ -0,0 +1,79 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.ArtworkVariants
+import com.margelo.nitro.audiobrowser.Variant_String_ArtworkVariants
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.descriptors.buildClassSerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+import kotlinx.serialization.json.JsonDecoder
+import kotlinx.serialization.json.JsonEncoder
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+
+/**
+ * A track's `artwork` on the wire: a URL string, or `{ light, dark }`.
+ *
+ * These models are the browse-response format, so this is what decides whether a payload parses at
+ * all — a plain `String?` here rejects the whole page, however tolerant the layers above it are.
+ *
+ * Android Auto is dark-only and never renders the light variant, but it is still parsed rather than
+ * discarded: the same payload feeds the JS side, and dropping half of it here would make the
+ * platforms disagree about what the server actually sent.
+ */
+@Serializable(with = JsonArtworkSerializer::class)
+sealed class JsonArtwork {
+  data class Single(val url: String) : JsonArtwork()
+
+  data class Variants(val light: String, val dark: String) : JsonArtwork()
+
+  /** The Nitro union this maps onto, one case per case. */
+  fun toNitro(): Variant_String_ArtworkVariants =
+    when (this) {
+      is Single -> Variant_String_ArtworkVariants.First(url)
+      is Variants -> Variant_String_ArtworkVariants.Second(ArtworkVariants(light, dark))
+    }
+}
+
+/**
+ * Discriminates on the JSON shape rather than a type tag, because the wire format has none — the
+ * server sends either a bare string or an object, and which one is the whole signal.
+ */
+object JsonArtworkSerializer : KSerializer<JsonArtwork> {
+  override val descriptor: SerialDescriptor = buildClassSerialDescriptor("JsonArtwork")
+
+  override fun deserialize(decoder: Decoder): JsonArtwork {
+    val input =
+      decoder as? JsonDecoder
+        ?: throw IllegalStateException("JsonArtwork can only be read from JSON")
+    return when (val element = input.decodeJsonElement()) {
+      is JsonPrimitive -> JsonArtwork.Single(element.content)
+      else ->
+        element.jsonObject.let {
+          JsonArtwork.Variants(
+            light = it.getValue("light").jsonPrimitive.content,
+            dark = it.getValue("dark").jsonPrimitive.content,
+          )
+        }
+    }
+  }
+
+  override fun serialize(encoder: Encoder, value: JsonArtwork) {
+    val output =
+      encoder as? JsonEncoder
+        ?: throw IllegalStateException("JsonArtwork can only be written as JSON")
+    output.encodeJsonElement(
+      when (value) {
+        is JsonArtwork.Single -> JsonPrimitive(value.url)
+        is JsonArtwork.Variants ->
+          JsonObject(
+            mapOf("light" to JsonPrimitive(value.light), "dark" to JsonPrimitive(value.dark))
+          )
+      }
+    )
+  }
+}

package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt

@@ -4,6 +4,7 @@ import com.margelo.nitro.audiobrowser.CarPlaySiriListButtonPosition
 import com.margelo.nitro.audiobrowser.ImageRowItem
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.Track
+import com.margelo.nitro.audiobrowser.TrackRequest
 import com.margelo.nitro.audiobrowser.TrackStyle
 import kotlinx.serialization.Serializable
 
@@ -13,19 +14,38 @@ import kotlinx.serialization.Serializable
  */
 @Serializable
 data class JsonImageRowItem(
+  val id: String? = null,
   val url: String? = null,
+  val src: String? = null,
   val artwork: String? = null,
   val title: String,
+  val artist: String? = null,
+  val album: String? = null,
+  val albumUrl: String? = null,
+  val live: Boolean? = null,
+  val request: JsonTrackRequest? = null,
 )
 
+/** JSON model for a track's per-request HTTP override (identity/auth/signed-url). */
+@Serializable
+data class JsonTrackRequest(
+  val userAgent: String? = null,
+  val headers: Map<String, String>? = null,
+  val query: Map<String, String>? = null,
+) {
+  fun toNitro(): TrackRequest = TrackRequest(userAgent, headers, query)
+}
+
 @Serializable
 data class JsonResolvedTrack(
+  val id: String? = null,
   val url: String,
   val title: String,
   val subtitle: String? = null,
   val icon: String? = null,
-  val artwork: String? = null,
+  val artwork: JsonArtwork? = null,
   val artist: String? = null,
+  val albumUrl: String? = null,
   val album: String? = null,
   val description: String? = null,
   val genre: String? = null,
@@ -41,17 +61,20 @@ data class JsonResolvedTrack(
 
 @Serializable
 data class JsonTrack(
+  val id: String? = null,
   val url: String? = null,
   val title: String,
   val subtitle: String? = null,
   val icon: String? = null,
-  val artwork: String? = null,
+  val artwork: JsonArtwork? = null,
   val artist: String? = null,
+  val albumUrl: String? = null,
   val album: String? = null,
   val description: String? = null,
   val genre: String? = null,
   val duration: Double? = null,
   val src: String? = null,
+  val request: JsonTrackRequest? = null,
   val style: String? = null,
   val childrenStyle: String? = null,
   val groupTitle: String? = null,
@@ -78,24 +101,35 @@ private fun String?.toCarPlaySiriListButtonPosition(): CarPlaySiriListButtonPosi
 
 private fun JsonImageRowItem.toNitro(): ImageRowItem {
   return ImageRowItem(
+    id = id,
     url = url,
+    src = src,
     artwork = artwork,
     artworkSource = null,
     title = title,
+    artist = artist,
+    album = album,
+    albumUrl = albumUrl,
+    live = live,
+    request = request?.toNitro(),
   )
 }
 
 fun JsonResolvedTrack.toNitro(): ResolvedTrack {
   return ResolvedTrack(
+    id = id,
     url = url,
     children = children?.map { it.toNitro() }?.toTypedArray(),
     carPlaySiriListButton = carPlaySiriListButton.toCarPlaySiriListButtonPosition(),
     title = title,
     subtitle = subtitle,
-    artwork = artwork,
+    artwork = artwork?.toNitro(),
     artworkSource = null,
+    // Containers carry no per-track media-request override (mirrors iOS JsonResolvedTrack).
+    request = null,
     artworkCarPlayTinted = null,
     artist = artist,
+    albumUrl = albumUrl,
     album = album,
     description = description,
     genre = genre,
@@ -112,13 +146,16 @@ fun JsonResolvedTrack.toNitro(): ResolvedTrack {
 
 fun JsonTrack.toNitro(): Track {
   return Track(
+    id = id,
     url = url,
     title = title,
     subtitle = subtitle,
-    artwork = artwork,
+    artwork = artwork?.toNitro(),
     artworkSource = null,
+    request = request?.toNitro(),
     artworkCarPlayTinted = null,
     artist = artist,
+    albumUrl = albumUrl,
     album = album,
     description = description,
     genre = genre,

package/android/src/main/java/com/audiobrowser/browser/SectionScope.kt

@@ -0,0 +1,43 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.ImageRowItem
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * Queue scope is the tapped section, not the whole page (ADR 0006): the
+ * playback context a listener expects is the list they tapped in — a page
+ * aggregating several sections must not leak next/previous across them.
+ */
+object SectionScope {
+  sealed class Section {
+    /** The tapped id lives inside an image row's items. */
+    data class ImageRow(val items: List<ImageRowItem>) : Section()
+
+    /**
+     * The contiguous `groupTitle` run around the tapped child (items with no
+     * group title form runs of their own).
+     */
+    data class Run(val tracks: List<Track>) : Section()
+  }
+
+  /**
+   * The section of [children] containing the playable [trackId], or null
+   * when the id is not found.
+   */
+  fun section(children: List<Track>, trackId: String): Section? {
+    for (child in children) {
+      val items = child.imageRow
+      if (items != null && items.any { it.src == trackId }) {
+        return Section.ImageRow(items.toList())
+      }
+    }
+    val index = children.indexOfFirst { it.src == trackId }
+    if (index < 0) return null
+    val group = children[index].groupTitle
+    var start = index
+    while (start > 0 && children[start - 1].groupTitle == group) start--
+    var end = index
+    while (end + 1 < children.size && children[end + 1].groupTitle == group) end++
+    return Section.Run(children.subList(start, end + 1).toList())
+  }
+}

package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt

@@ -1,7 +1,7 @@
 package com.audiobrowser.browser
 
-import com.margelo.nitro.audiobrowser.TrackLoadEvent
 import com.margelo.nitro.audiobrowser.Track
+import com.margelo.nitro.audiobrowser.TrackLoadEvent
 import com.margelo.nitro.core.Promise
 import timber.log.Timber
 
@@ -11,8 +11,8 @@ import timber.log.Timber
  * If the handler is present, awaits it and returns [intercepted]. Otherwise runs [default].
  *
  * Nitro wraps value-returning JS callbacks in Promise<T> for thread safety, so a JS callback
- * returning Promise<void> becomes Promise<Promise<Unit>> on the native side. Both layers
- * must be awaited to properly wait for the JS work to complete.
+ * returning Promise<void> becomes Promise<Promise<Unit>> on the native side. Both layers must be
+ * awaited to properly wait for the JS work to complete.
  *
  * @param handler The handleTrackLoad callback from NativeBrowserConfiguration, or null
  * @param track The track being loaded
@@ -27,7 +27,7 @@ suspend fun <T> handleTrackLoad(
   track: Track,
   queue: Array<Track>,
   startIndex: Double,
-  intercepted: () -> T,
+  intercepted: suspend () -> T,
   defaultBehavior: suspend () -> T,
 ): T {
   if (handler != null) {

package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt

@@ -0,0 +1,35 @@
+package com.audiobrowser.extension
+
+import com.margelo.nitro.audiobrowser.ResolvedTrack
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * The Track view of a ResolvedTrack: every display/playback field carried over, the browse-only
+ * fields (`children`, `carPlaySiriListButton`) dropped. The one place that knows the two shapes
+ * share their field set — used to funnel ResolvedTracks through the single Track→MediaItem
+ * conversion in TrackFactory.
+ */
+fun ResolvedTrack.toTrack(): Track =
+  Track(
+    id = id,
+    url = url,
+    src = src,
+    artwork = artwork,
+    artworkSource = artworkSource,
+    request = request,
+    artworkCarPlayTinted = artworkCarPlayTinted,
+    title = title,
+    subtitle = subtitle,
+    artist = artist,
+    albumUrl = albumUrl,
+    album = album,
+    description = description,
+    genre = genre,
+    duration = duration,
+    style = style,
+    childrenStyle = childrenStyle,
+    favorited = favorited,
+    groupTitle = groupTitle,
+    live = live,
+    imageRow = imageRow,
+  )