react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/src/web/browser/FavoriteManager.ts

@@ -1,14 +1,16 @@
 import type { Track, ResolvedTrack } from '../../types'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
 
 /**
- * Manages favorite state for tracks.
+ * Manages favorite state for tracks, keyed by track identity (`id` when set,
+ * falling back to `src` — see getTrackIdentity / ADR 0008).
  * Matches Android's favorite hydration behavior.
  */
 export class FavoriteManager {
   private favorites = new Set<string>()
 
   /**
-   * Sets the favorites cache from an array of track src values.
+   * Sets the favorites cache from an array of track identities.
    * This is typically called when favorites are loaded from storage.
    */
   setFavorites(favorites: string[]): void {
@@ -16,24 +18,27 @@ export class FavoriteManager {
   }
 
   /**
-   * Checks if a track is favorited based on its src.
+   * Checks if a track is favorited based on its identity.
    */
-  isFavorited(src: string): boolean {
-    return this.favorites.has(src)
+  isFavorited(track: Track): boolean {
+    const identity = getTrackIdentity(track)
+    return identity !== undefined && this.favorites.has(identity)
   }
 
   /**
-   * Adds a track src to the favorites cache.
+   * Adds a track to the favorites cache under its identity.
    */
-  addFavorite(src: string): void {
-    this.favorites.add(src)
+  addFavorite(track: Track): void {
+    const identity = getTrackIdentity(track)
+    if (identity !== undefined) this.favorites.add(identity)
   }
 
   /**
-   * Removes a track src from the favorites cache.
+   * Removes a track from the favorites cache under its identity.
    */
-  removeFavorite(src: string): void {
-    this.favorites.delete(src)
+  removeFavorite(track: Track): void {
+    const identity = getTrackIdentity(track)
+    if (identity !== undefined) this.favorites.delete(identity)
   }
 
   /**
@@ -48,8 +53,7 @@ export class FavoriteManager {
     if (track.favorited !== undefined && track.favorited !== null) return track
     if (this.favorites.size === 0) return track
 
-    const isFavorited = track.src ? this.favorites.has(track.src) : false
-    if (!isFavorited) return track
+    if (!this.isFavorited(track)) return track
 
     return {
       ...track,
@@ -58,22 +62,23 @@ export class FavoriteManager {
   }
 
   /**
-   * Hydrates favorites on all children of a ResolvedTrack.
-   * Matches Android's hydrateChildren behavior.
+   * Hydrates favorites on all tracks of a resolved page.
+   * Matches Android's hydrateChildren behavior. Pages reach hydration
+   * normalized (ADR 0010), so `sections` is the only structure to walk.
    *
-   * @param resolvedTrack ResolvedTrack with children to hydrate
-   * @returns ResolvedTrack with favorited properties set on children
+   * @param resolvedTrack Resolved page to hydrate
+   * @returns Resolved page with favorited properties set on its tracks
    */
   hydrateChildren(resolvedTrack: ResolvedTrack): ResolvedTrack {
-    const children = resolvedTrack.children
-    if (!children) return resolvedTrack
+    const { sections } = resolvedTrack
+    if (!sections) return resolvedTrack
 
-    const hydratedChildren = children.map((track) =>
-      this.hydrateFavorite(track)
-    )
     return {
       ...resolvedTrack,
-      children: hydratedChildren
+      sections: sections.map((section) => ({
+        ...section,
+        children: section.children.map((track) => this.hydrateFavorite(track))
+      }))
     }
   }
 }

package/src/web/browser/NavigationErrorManager.ts

@@ -5,6 +5,7 @@ import type {
   NavigationErrorEvent
 } from '../../features'
 import type { NativeBrowserConfiguration } from '../../types/browser-native'
+import { BrowserPathHelper } from '../util/BrowserPathHelper'
 
 const ERROR_TITLES: Record<NavigationErrorType, string> = {
   'network-error': 'Network Error',
@@ -91,7 +92,8 @@ export class NavigationErrorManager {
         const customFormatted = this.formatCallback({
           error: navError,
           defaultFormatted,
-          path
+          path,
+          kind: BrowserPathHelper.navigationErrorKind(path)
         })
         this._formattedNavigationError = customFormatted || defaultFormatted
       } catch (error) {

package/src/web/browser/SearchManager.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { NativeBrowserConfiguration } from '../../types/browser-native'
+import type { HttpClient } from '../http/HttpClient'
+import { BrowserManager } from './BrowserManager'
+import { FavoriteManager } from './FavoriteManager'
+import { NavigationErrorManager } from './NavigationErrorManager'
+import { SearchManager } from './SearchManager'
+
+/**
+ * Builds a SearchManager over a BrowserManager whose HTTP client answers every
+ * request with `respond` — a resolved body or a rejection.
+ */
+function makeSearchManager(
+  respond: () => Promise<unknown>,
+  route: NonNullable<NativeBrowserConfiguration['routes']>[number] = {
+    path: '__search__',
+    searchConfig: { baseUrl: 'https://api.example.com' }
+  }
+): SearchManager {
+  const httpClient = {
+    executeRequest: vi.fn().mockImplementation(respond)
+  } as unknown as HttpClient
+  const browserManager = new BrowserManager(
+    httpClient,
+    new FavoriteManager(),
+    new NavigationErrorManager()
+  )
+  browserManager.configuration = { routes: [route] }
+  return new SearchManager(browserManager)
+}
+
+const httpError = (): Error => {
+  const error = new Error('HTTP 500: Internal Server Error') as Error & {
+    code: string
+    statusCode: number
+  }
+  error.code = 'http-error'
+  error.statusCode = 500
+  return error
+}
+
+describe('SearchManager', () => {
+  it('rejects when the search request fails', async () => {
+    const manager = makeSearchManager(() => Promise.reject(httpError()))
+    await expect(
+      manager.search({ query: 'jazz', reference: 'unknown' })
+    ).rejects.toThrow('HTTP 500: Internal Server Error')
+  })
+
+  it('resolves [] when the search found nothing', async () => {
+    const manager = makeSearchManager(() => Promise.resolve({ children: [] }))
+    await expect(
+      manager.search({ query: 'jazz', reference: 'unknown' })
+    ).resolves.toEqual([])
+  })
+
+  it('resolves the matching tracks', async () => {
+    const manager = makeSearchManager(() =>
+      Promise.resolve({ children: [{ title: 'Jazz FM', src: 'https://s/1' }] })
+    )
+    await expect(
+      manager.search({ query: 'jazz', reference: 'unknown' })
+    ).resolves.toEqual([{ title: 'Jazz FM', src: 'https://s/1' }])
+  })
+
+  it('propagates a rejecting search callback', async () => {
+    const manager = makeSearchManager(() => Promise.resolve([]), {
+      path: '__search__',
+      searchCallback: () => Promise.reject(new Error('callback exploded'))
+    })
+    await expect(
+      manager.search({ query: 'jazz', reference: 'unknown' })
+    ).rejects.toThrow('callback exploded')
+  })
+})

package/src/web/browser/SearchManager.ts

@@ -15,7 +15,9 @@ export class SearchManager {
    * Matches Android's BrowserManager.search(params: SearchParams) behavior.
    *
    * @param params Search parameters (query is required, other fields optional)
-   * @returns Array of matching tracks
+   * @returns Array of matching tracks — empty only when the source found none
+   * @throws The failure itself: an `Error` carrying a `NavigationErrorType`
+   *   `code` from `HttpClient`, or whatever a `searchCallback` rejected with
    */
   async search(params: SearchParams): Promise<Track[]> {
     // Find __search__ route entry
@@ -48,36 +50,31 @@ export class SearchManager {
 
       // Delegate to the shared layered fetch (request → search) on BrowserManager
       // so the ladder lives in one place.
-      try {
-        results = await this.browserManager.fetchSearchResults(
-          searchRoute.searchConfig,
-          searchQueryParams
-        )
-      } catch (error) {
-        console.error('Search failed:', error)
-        return []
-      }
+      results = await this.browserManager.fetchSearchResults(
+        searchRoute.searchConfig,
+        searchQueryParams
+      )
     }
 
     // Transform artwork URLs on search results using async method with full Track access
-    const { request: requestConfig, artwork: artworkConfig } =
-      this.browserManager.configuration
-    if (artworkConfig) {
-      results = await Promise.all(
-        results.map(async (track) => {
-          const artworkSource =
-            await RequestConfigBuilder.resolveArtworkSourceAsync(
-              track,
-              requestConfig,
-              artworkConfig
-            )
-          if (artworkSource && !track.artworkSource) {
-            return { ...track, artworkSource }
-          }
-          return track
-        })
-      )
-    }
+    // Gated per track inside the resolver, as on Android — a result carrying a
+    // plain `artwork` URL resolves even with no `artwork` config.
+    const requestConfig = await this.browserManager.resolvedRequestConfig()
+    const artworkConfig = this.browserManager.configuration.artwork
+    results = await Promise.all(
+      results.map(async (track) => {
+        const artworkSource =
+          await RequestConfigBuilder.resolveArtworkSourceAsync(
+            track,
+            requestConfig,
+            artworkConfig
+          )
+        if (artworkSource && !track.artworkSource) {
+          return { ...track, artworkSource }
+        }
+        return track
+      })
+    )
 
     return results
   }

package/src/web/browser/__tests__/artwork-resolution.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { HttpClient } from '../../http/HttpClient'
+import { BrowserManager } from '../BrowserManager'
+import { FavoriteManager } from '../FavoriteManager'
+import { NavigationErrorManager } from '../NavigationErrorManager'
+
+function makeManager(): BrowserManager {
+  const httpClient = {
+    executeRequest: vi.fn().mockRejectedValue(new Error('no network in test'))
+  } as unknown as HttpClient
+  return new BrowserManager(
+    httpClient,
+    new FavoriteManager(),
+    new NavigationErrorManager()
+  )
+}
+
+/**
+ * Who gets an `artworkSource`, and on whose say-so.
+ *
+ * Android gates this per *track* — `resolveArtworkUrl` returns early only when
+ * `artworkConfig == null && track.artwork == null`, so a track carrying a plain
+ * URL resolves to `{ uri }` with no `artwork` block configured at all. Web used
+ * to gate a level up, bailing out of the whole page when `configuration.artwork`
+ * was unset, which left every child's `artworkSource` undefined in any app that
+ * never declared one — the example app among them.
+ */
+describe('artwork resolution without an artwork config', () => {
+  it('populates artworkSource for a child carrying a plain artwork url', async () => {
+    const manager = makeManager()
+    manager.configuration = {
+      path: '/',
+      routes: [
+        {
+          path: '/library',
+          browseStatic: {
+            path: '/library',
+            title: 'Library',
+            sections: [
+              {
+                title: 'Collections',
+                children: [
+                  {
+                    title: 'Cratediggers',
+                    path: '/collection/cratediggers',
+                    artwork: 'https://cdn.example.com/cratediggers.jpg'
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+
+    await manager.navigatePath('/library')
+
+    const tile = manager.content?.sections?.[0]?.children[0]
+    expect(tile?.artworkSource?.uri).toBe(
+      'https://cdn.example.com/cratediggers.jpg'
+    )
+  })
+
+  it('leaves artworkSource undefined for a child with no artwork', async () => {
+    const manager = makeManager()
+    manager.configuration = {
+      path: '/',
+      routes: [
+        {
+          path: '/library',
+          browseStatic: {
+            path: '/library',
+            title: 'Library',
+            sections: [
+              {
+                title: 'Collections',
+                children: [{ title: 'Bare', path: '/collection/bare' }]
+              }
+            ]
+          }
+        }
+      ]
+    }
+
+    await manager.navigatePath('/library')
+
+    const tile = manager.content?.sections?.[0]?.children[0]
+    expect(tile?.artworkSource).toBeUndefined()
+  })
+
+  it('treats an empty artwork string as no artwork, as Android does', async () => {
+    const manager = makeManager()
+    manager.configuration = {
+      path: '/',
+      routes: [
+        {
+          path: '/library',
+          browseStatic: {
+            path: '/library',
+            title: 'Library',
+            sections: [
+              {
+                title: 'Collections',
+                children: [{ title: 'Empty', path: '/x', artwork: '' }]
+              }
+            ]
+          }
+        }
+      ]
+    }
+
+    await manager.navigatePath('/library')
+
+    const tile = manager.content?.sections?.[0]?.children[0]
+    expect(tile?.artworkSource).toBeUndefined()
+  })
+})

package/src/web/browser/__tests__/layer-resolver.test.ts

@@ -66,4 +66,39 @@ describe('BrowserManager layer resolver', () => {
     await expect(manager.navigatePath('/a')).resolves.not.toThrow()
     expect(calls).toBe(1)
   })
+
+  /**
+   * The media and artwork paths sit outside browse and so must reach the
+   * request layer through this accessor. Reading `configuration.request`
+   * instead hands a resolver-only config no baseUrl and no headers — on
+   * exactly the requests that carry a credential. Android's
+   * `resolvedRequestConfig()` exists for the same reason.
+   */
+  it('exposes the resolver result to consumers outside the browse path', async () => {
+    const manager = makeManager()
+    manager.configuration = {
+      path: '/',
+      requestResolver: async () => ({
+        baseUrl: 'https://api.example.com',
+        headers: { Authorization: 'Bearer token' }
+      })
+    }
+
+    expect(await manager.resolvedRequestConfig()).toEqual({
+      baseUrl: 'https://api.example.com',
+      headers: { Authorization: 'Bearer token' }
+    })
+  })
+
+  it('falls back to the static request config when no resolver is set', async () => {
+    const manager = makeManager()
+    manager.configuration = {
+      path: '/',
+      request: { baseUrl: 'https://static.example.com' }
+    }
+
+    expect(await manager.resolvedRequestConfig()).toEqual({
+      baseUrl: 'https://static.example.com'
+    })
+  })
 })

package/src/web/browser/__tests__/search-artwork.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { HttpClient } from '../../http/HttpClient'
+import { BrowserManager } from '../BrowserManager'
+import { FavoriteManager } from '../FavoriteManager'
+import { NavigationErrorManager } from '../NavigationErrorManager'
+import { SearchManager } from '../SearchManager'
+
+/**
+ * Search-result artwork reaches the request layer through
+ * `resolvedRequestConfig()`, as content and media artwork do. Reading
+ * `configuration.request` handed a resolver-only config no baseUrl and no
+ * headers, so a relative artwork path on a search result never resolved.
+ */
+describe('search result artwork', () => {
+  it('applies a resolver-only request layer', async () => {
+    const httpClient = {
+      executeRequest: vi
+        .fn()
+        .mockResolvedValue([
+          { title: 'Hit', src: '/hit.mp3', artwork: '/art/hit.jpg' }
+        ])
+    } as unknown as HttpClient
+    const manager = new BrowserManager(
+      httpClient,
+      new FavoriteManager(),
+      new NavigationErrorManager()
+    )
+    manager.configuration = {
+      path: '/',
+      requestResolver: async () => ({
+        baseUrl: 'https://api.example.com',
+        headers: { Authorization: 'Bearer t' }
+      }),
+      artwork: {},
+      routes: [{ path: '__search__', searchConfig: { path: '/search' } }]
+    }
+
+    const [hit] = await new SearchManager(manager).search({
+      query: 'hit',
+      reference: 'unknown'
+    })
+
+    expect(hit?.artworkSource?.uri).toBe('https://api.example.com/art/hit.jpg')
+    expect(hit?.artworkSource?.headers).toEqual({ Authorization: 'Bearer t' })
+  })
+})

package/src/web/browser/__tests__/search-navigation.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { FormattedNavigationError } from '../../../features'
+import type { HttpClient } from '../../http/HttpClient'
+import { BrowserManager } from '../BrowserManager'
+import { FavoriteManager } from '../FavoriteManager'
+import { NavigationErrorManager } from '../NavigationErrorManager'
+
+/**
+ * A BrowserManager whose only route is a `searchConfig`, with its HTTP client
+ * answering every request with `respond`.
+ */
+function makeManager(respond: () => Promise<unknown>): {
+  manager: BrowserManager
+  errors: NavigationErrorManager
+  formattedPaths: string[]
+} {
+  const httpClient = {
+    executeRequest: vi.fn().mockImplementation(respond)
+  } as unknown as HttpClient
+  const errors = new NavigationErrorManager()
+  const manager = new BrowserManager(httpClient, new FavoriteManager(), errors)
+  const formattedPaths: string[] = []
+  manager.configuration = {
+    routes: [
+      {
+        path: '__search__',
+        searchConfig: { baseUrl: 'https://api.example.com' }
+      }
+    ],
+    formatNavigationError: ({ path }): FormattedNavigationError => {
+      formattedPaths.push(path)
+      return { title: 'Search unavailable' }
+    }
+  }
+  return { manager, errors, formattedPaths }
+}
+
+const httpError = (): Error => {
+  const error = new Error('HTTP 500: Internal Server Error') as Error & {
+    code: string
+    statusCode: number
+  }
+  error.code = 'http-error'
+  error.statusCode = 500
+  return error
+}
+
+describe('navigating to a search path', () => {
+  it('surfaces a navigation error when the search fails', async () => {
+    const { manager, errors, formattedPaths } = makeManager(() =>
+      Promise.reject(httpError())
+    )
+
+    await manager.navigatePath('/__search?q=jazz')
+
+    expect(errors.getNavigationError()).toEqual({
+      code: 'http-error',
+      message: 'HTTP 500: Internal Server Error',
+      statusCode: 500,
+      statusCodeSuccess: undefined
+    })
+    expect(formattedPaths).toEqual(['/__search?q=jazz'])
+    expect(manager.content).toBeUndefined()
+  })
+
+  it('resolves an empty page without an error when the search found nothing', async () => {
+    const { manager, errors } = makeManager(() =>
+      Promise.resolve({ children: [] })
+    )
+
+    await manager.navigatePath('/__search?q=jazz')
+
+    expect(errors.getNavigationError()).toBeUndefined()
+    expect(manager.content?.sections).toEqual([{ children: [] }])
+  })
+})

package/src/web/browser/assertBrowsePageShape.test.ts

@@ -3,7 +3,7 @@ import { assertBrowsePageShape } from './assertBrowsePageShape'
 
 describe('assertBrowsePageShape', () => {
   it('passes a page object through unchanged', () => {
-    const page = { url: '/x', title: 'X', children: [] }
+    const page = { path: '/x', title: 'X', children: [] }
     expect(assertBrowsePageShape(page, '/x')).toBe(page)
   })
 

package/src/web/browser/assertBrowsePageShape.ts

@@ -13,14 +13,16 @@ export function assertBrowsePageShape(
   if (Array.isArray(response)) {
     throw new Error(
       `Browse endpoint for "${path}" returned a JSON array; expected a ` +
-        `page object { title, children?: Track[] }. Wrap the rows in a ` +
-        `\`children\` array.`
+        `page object { title, sections?: Section[], children?: Track[] }. ` +
+        `Wrap the rows in a \`children\` array (one untitled section) or ` +
+        `group them into \`sections\`.`
     )
   }
   if (response === null || typeof response !== 'object') {
     throw new Error(
       `Browse endpoint for "${path}" returned ${JSON.stringify(response)}; ` +
-        `expected a page object { title, children?: Track[] }.`
+        `expected a page object { title, sections?: Section[], ` +
+        `children?: Track[] }.`
     )
   }
   return response as ResolvedTrack

package/src/web/browser/classifyTrackNavigation.test.ts

@@ -5,10 +5,10 @@ import { classifyTrackNavigation } from './classifyTrackNavigation'
 const track = (fields: Partial<Track>): Track => fields as Track
 
 describe('classifyTrackNavigation', () => {
-  it('classifies a contextual url, exposing parent path and track id', () => {
+  it('classifies a contextual path, exposing parent path and track id', () => {
     expect(
       classifyTrackNavigation(
-        track({ url: '/library/radio?__trackId=song.mp3' })
+        track({ path: '/library/radio?__trackId=song.mp3' })
       )
     ).toEqual({
       kind: 'contextual',
@@ -17,25 +17,27 @@ describe('classifyTrackNavigation', () => {
     })
   })
 
-  it('classifies a non-contextual url as a browse navigation', () => {
-    expect(classifyTrackNavigation(track({ url: '/library/radio' }))).toEqual({
+  it('classifies a non-contextual path as a browse navigation', () => {
+    expect(classifyTrackNavigation(track({ path: '/library/radio' }))).toEqual({
       kind: 'browse'
     })
   })
 
-  it('classifies a track with src but no url as playable', () => {
+  it('classifies a track with src but no path as playable', () => {
     expect(classifyTrackNavigation(track({ src: 'song.mp3' }))).toEqual({
       kind: 'playable'
     })
   })
 
-  it('prefers browse over playable when a url is present', () => {
+  it('prefers browse over playable when a path is present', () => {
     expect(
-      classifyTrackNavigation(track({ url: '/library/radio', src: 'song.mp3' }))
+      classifyTrackNavigation(
+        track({ path: '/library/radio', src: 'song.mp3' })
+      )
     ).toEqual({ kind: 'browse' })
   })
 
-  it('classifies a track with neither url nor src as invalid', () => {
+  it('classifies a track with neither path nor src as invalid', () => {
     expect(classifyTrackNavigation(track({}))).toEqual({ kind: 'invalid' })
   })
 })

package/src/web/browser/classifyTrackNavigation.ts

@@ -4,10 +4,10 @@ import { BrowserPathHelper } from '../util/BrowserPathHelper'
 /**
  * How a selected track should be navigated, decided purely from its shape:
  * - `contextual` — a playable track carrying its parent queue context in a
- *   contextual URL (`{parentPath}?__trackId={src}`); expand/skip within that queue.
- * - `browse` — a browsable track (has a `url` that isn't contextual); drill in.
- * - `playable` — a bare playable track (`src`, no `url`); load and play it alone.
- * - `invalid` — neither `url` nor `src`; nothing to do.
+ *   contextual path (`{parentPath}?__trackId={src}`); expand/skip within that queue.
+ * - `browse` — a browsable track (has a `path` that isn't contextual); drill in.
+ * - `playable` — a bare playable track (`src`, no `path`); load and play it alone.
+ * - `invalid` — neither `path` nor `src`; nothing to do.
  */
 export type TrackNavigation =
   | { kind: 'contextual'; parentPath: string; trackId: string | undefined }
@@ -21,15 +21,15 @@ export type TrackNavigation =
  * caller; this only decides which action applies.
  */
 export function classifyTrackNavigation(track: Track): TrackNavigation {
-  const url = track.url
-  if (url && BrowserPathHelper.isContextual(url)) {
+  const path = track.path
+  if (path && BrowserPathHelper.isContextual(path)) {
     return {
       kind: 'contextual',
-      parentPath: BrowserPathHelper.stripTrackId(url),
-      trackId: BrowserPathHelper.extractTrackId(url)
+      parentPath: BrowserPathHelper.stripTrackId(path),
+      trackId: BrowserPathHelper.extractTrackId(path)
     }
   }
-  if (url) return { kind: 'browse' }
+  if (path) return { kind: 'browse' }
   if (track.src) return { kind: 'playable' }
   return { kind: 'invalid' }
 }