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

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { parseSearchResponse } from './parseSearchResponse'
+
+describe('parseSearchResponse', () => {
+  it('extracts children from a page-object response', () => {
+    const tracks = [{ src: '/a', title: 'A' }]
+    expect(
+      parseSearchResponse({ url: '/search', title: 'Search', children: tracks })
+    ).toEqual(tracks)
+  })
+
+  it('returns a bare array response unchanged (back-compat)', () => {
+    const tracks = [{ src: '/a', title: 'A' }]
+    expect(parseSearchResponse(tracks)).toEqual(tracks)
+  })
+
+  it('returns [] for a page object with no children', () => {
+    expect(parseSearchResponse({ url: '/search', title: 'Search' })).toEqual([])
+  })
+
+  it('returns [] for null / non-object responses', () => {
+    expect(parseSearchResponse(null)).toEqual([])
+    expect(parseSearchResponse('nope')).toEqual([])
+  })
+})

package/src/web/browser/parseSearchResponse.ts

@@ -0,0 +1,15 @@
+import type { Track } from '../../types'
+
+/**
+ * Normalise a search endpoint's HTTP body into `Track[]`. Endpoints return the
+ * audio-browser page shape `{ children: Track[] }` (matching iOS/Android, which
+ * decode a ResolvedTrack and read `.children`). A bare `Track[]` is still
+ * accepted for back-compat with callback/array-returning sources.
+ */
+export function parseSearchResponse(response: unknown): Track[] {
+  if (Array.isArray(response)) return response as Track[]
+  if (response && typeof response === 'object' && 'children' in response) {
+    return (response as { children?: Track[] }).children ?? []
+  }
+  return []
+}

package/src/web/http/HttpClient.ts

@@ -1,5 +1,5 @@
 import type { NavigationErrorType } from '../../features'
-import type { RequestConfig, TransformableRequestConfig } from '../../types'
+import type { RequestConfig } from '../../types'
 import { RequestConfigBuilder } from './RequestConfigBuilder'
 
 type HttpError = Error & {
@@ -23,42 +23,12 @@ const TIMEOUT_MS = 30_000
 /**
  * HTTP client for making browser API requests.
  * Mirrors Android's HttpClient.kt
- * Uses RequestConfigBuilder for URL building and config merging.
+ *
+ * Config layering (the shared `request` → `<kind>` → route chain) is handled by
+ * the callers via RequestConfigBuilder.applyLayer; this client just builds the
+ * URL from the fully-merged config and executes the request.
  */
 export class HttpClient {
-  private baseRequestConfig: Partial<TransformableRequestConfig>
-
-  constructor(baseRequestConfig: Partial<TransformableRequestConfig> = {}) {
-    this.baseRequestConfig = baseRequestConfig
-  }
-
-  /**
-   * Updates the base request configuration used for all requests.
-   */
-  setBaseRequestConfig(config: Partial<TransformableRequestConfig>): void {
-    this.baseRequestConfig = config
-  }
-
-  /**
-   * Merges multiple request configs with proper header and query parameter merging.
-   * Uses RequestConfigBuilder for consistent merging behavior.
-   */
-  mergeRequestConfig(
-    base: Partial<TransformableRequestConfig>,
-    overrides: Partial<RequestConfig>
-  ): RequestConfig {
-    // First merge base with the instance's base config
-    const withBase = RequestConfigBuilder.mergeConfig(
-      this.baseRequestConfig as RequestConfig,
-      base as RequestConfig
-    )
-    // Then merge with overrides
-    return RequestConfigBuilder.mergeConfig(
-      withBase,
-      overrides as RequestConfig
-    )
-  }
-
   /**
    * Executes an HTTP request and returns the JSON response.
    * Throws navigation errors for HTTP and network failures.

package/src/web/http/RequestConfigBuilder.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest'
+import type { RequestConfig, TransformableRequestConfig } from '../../types'
+import { RequestConfigBuilder } from './RequestConfigBuilder'
+
+/**
+ * Composition tests for the sync/async `transform` split. These lock down the
+ * run-both pipeline (async first, then sync) so a regression in the layering
+ * logic is caught. NOTE: they do NOT exercise the JS↔native Nitro bridge — the
+ * original "async returns an empty config" bug lived there and is structurally
+ * invisible to a pure-JS test. See the codegen regression guard for that.
+ */
+describe('RequestConfigBuilder.applyLayer — sync/async transform composition', () => {
+  const base: RequestConfig = { baseUrl: 'https://api.example.com', path: '/p' }
+
+  it('applies an async transform', async () => {
+    const layer: TransformableRequestConfig = {
+      transform: async (req) => ({ ...req, headers: { a: '1' } })
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    expect(out.headers).toEqual({ a: '1' })
+    expect(out.baseUrl).toBe('https://api.example.com')
+  })
+
+  it('applies a sync transform', async () => {
+    const layer: TransformableRequestConfig = {
+      transformSync: (req) => ({ ...req, headers: { b: '2' } })
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    expect(out.headers).toEqual({ b: '2' })
+  })
+
+  it('runs both as a pipeline: async first, then sync sees the async output', async () => {
+    const order: string[] = []
+    const layer: TransformableRequestConfig = {
+      transform: async (req) => {
+        order.push('async')
+        return { ...req, query: { stage: 'async' } }
+      },
+      transformSync: (req) => {
+        order.push('sync')
+        // The sync stage must receive the async stage's output.
+        expect(req.query).toEqual({ stage: 'async' })
+        return { ...req, query: { ...req.query, stage: 'sync' } }
+      }
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    expect(order).toEqual(['async', 'sync'])
+    expect(out.query).toEqual({ stage: 'sync' })
+  })
+
+  it('falls back to a static field merge when no transform is set', async () => {
+    const layer: TransformableRequestConfig = {
+      baseUrl: 'https://override.example.com'
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    expect(out.baseUrl).toBe('https://override.example.com')
+    expect(out.path).toBe('/p')
+  })
+})

package/src/web/http/RequestConfigBuilder.ts

@@ -8,6 +8,7 @@ import type {
   ImageContext,
   ImageQueryParams
 } from '../../types'
+import { artworkUrl as resolveArtworkUrl } from '../../utils/artwork'
 import { BrowserPathHelper } from '../util/BrowserPathHelper'
 
 /**
@@ -93,46 +94,59 @@ export const RequestConfigBuilder = {
   },
 
   /**
-   * Merges a base RequestConfig with a MediaRequestConfig.
-   * Returns the merged config for use in media URL resolution.
-   * Supports the transform callback like Android's RequestConfigBuilder.
+   * Applies one request-config layer (request / kind / route) onto a base.
+   * A layer with a transform wins completely — it receives the base (plus route
+   * params) and its result replaces the base; the layer's own static fields are
+   * ignored. A layer without a transform merges its static fields over the base.
+   * `path` is carried from the base — only a transform may change it.
    *
-   * Note: MediaRequestConfig inherits transform from TransformableRequestConfig,
-   * which takes (request, routeParams?) directly, not MediaTransformParams.
+   * Mirrors native's BrowserManager.applyLayer so web resolves the shared
+   * `request` → `<kind>` → route chain identically across platforms.
    */
-  async mergeMediaConfig(
+  async applyLayer(
     base: RequestConfig,
-    override: MediaRequestConfig
+    layer: TransformableRequestConfig | undefined,
+    params?: Record<string, string>
   ): Promise<RequestConfig> {
-    // Apply transform function if provided - transform result wins completely
-    if (override.transform) {
-      try {
-        // TransformableRequestConfig.transform takes (request, routeParams?) directly
-        const transformed = await override.transform(base)
-        return transformed
-      } catch (e) {
-        console.error(
-          'Failed to apply media transform function, using base config',
-          e
-        )
-        return base
-      }
+    if (!layer) return base
+    // A transform (async and/or sync) wins completely: it receives the base and
+    // its result replaces it. When both are set they run as a pipeline — async
+    // first, then sync (mirrors native applyLayer).
+    if (layer.transform || layer.transformSync) {
+      let cfg = base
+      if (layer.transform) cfg = await layer.transform(cfg, params)
+      if (layer.transformSync) cfg = layer.transformSync(cfg, params)
+      return cfg
+    }
+    return {
+      method: layer.method ?? base.method,
+      path: base.path,
+      baseUrl: layer.baseUrl ?? base.baseUrl,
+      headers: this.mergeHeaders(base.headers, layer.headers),
+      query: this.mergeQuery(base.query, layer.query),
+      body: layer.body ?? base.body,
+      contentType: layer.contentType ?? base.contentType,
+      userAgent: layer.userAgent ?? base.userAgent
     }
-
-    // No transform - merge static config
-    return this.mergeConfig(base, this.toRequestConfig(override))
   },
 
   /**
-   * Merges a base RequestConfig with an ArtworkRequestConfig.
-   * Returns the merged config for use in artwork URL resolution.
+   * Applies an ordered list of layers onto a base via {@link applyLayer}, each
+   * layer receiving the previous one's output. `undefined` layers are skipped.
+   * This is the single primitive for the `request → <kind> → route` chain —
+   * browse, search, and media all build a base and reduce their layers through
+   * it, so the ladder lives in exactly one place.
    */
-  mergeArtworkConfig(
+  async applyLayers(
     base: RequestConfig,
-    override: ArtworkRequestConfig
-  ): RequestConfig {
-    // On web, we don't support resolve/transform callbacks - just merge the static config
-    return this.mergeConfig(base, this.toRequestConfig(override))
+    layers: (TransformableRequestConfig | undefined)[],
+    params?: Record<string, string>
+  ): Promise<RequestConfig> {
+    let merged = base
+    for (const layer of layers) {
+      merged = await this.applyLayer(merged, layer, params)
+    }
+    return merged
   },
 
   /**
@@ -161,39 +175,67 @@ export const RequestConfigBuilder = {
    * Creates a RequestConfig with the track's src as the path, then builds the URL.
    * Supports the transform callback for URL manipulation.
    *
+   * The shared `request` layer is applied first (its transform runs for media
+   * too, per the documented contract — e.g. a dynamic baseUrl), then the media
+   * transform / static fields on top. Mirrors native's resolveMediaUrl,
+   * including its best-effort behaviour: if a transform throws, fall back to the
+   * original `src` rather than failing the load.
+   *
    * @param src The track's src value (may be relative or absolute)
+   * @param requestConfig The shared request configuration (applied first)
    * @param mediaConfig The media request configuration
    * @returns The resolved absolute URL
    */
   async resolveMediaUrl(
     src: string,
+    requestConfig: TransformableRequestConfig | undefined,
     mediaConfig: MediaRequestConfig | undefined
   ): Promise<string> {
-    if (!mediaConfig) {
+    try {
+      const config = await this.applyLayers({ path: src }, [
+        requestConfig,
+        mediaConfig
+      ])
+      return BrowserPathHelper.buildUrl(config.baseUrl, config.path ?? src)
+    } catch (e) {
+      console.error('Failed to resolve media URL, using original src', e)
       return BrowserPathHelper.buildUrl(undefined, src)
     }
-
-    const config = await this.mergeMediaConfig({ path: src }, mediaConfig)
-    return BrowserPathHelper.buildUrl(config.baseUrl, config.path ?? src)
   },
 
   /**
    * Resolves an artwork URL and creates an ImageSource.
    * Matches Android's artwork URL transformation behavior.
    *
+   * The shared `request` layer's static fields are applied first; this sync path
+   * cannot run an async `request.transform`, so transform-based shaping (e.g. a
+   * dynamic baseUrl) only applies on the async resolution paths. Queue tracks
+   * usually already carry an `artworkSource` resolved at browse-time, so this
+   * sync fallback rarely runs.
+   *
    * @param artworkUrl The artwork URL (may be relative or absolute)
+   * @param requestConfig The shared request configuration (static fields only)
    * @param artworkConfig The artwork request configuration
    * @returns ImageSource with resolved URI, or undefined if no artwork
    */
   resolveArtworkSource(
     artworkUrl: string | undefined,
+    requestConfig: TransformableRequestConfig | undefined,
     artworkConfig: ArtworkRequestConfig | undefined
   ): ImageSource | undefined {
     if (!artworkUrl) return undefined
 
-    const config = artworkConfig
-      ? this.mergeArtworkConfig({ path: artworkUrl }, artworkConfig)
-      : { path: artworkUrl }
+    // Base path stays the artwork URL; the request layer contributes baseUrl /
+    // query / headers, then the artwork config overrides on top.
+    let config: RequestConfig = { path: artworkUrl }
+    if (requestConfig) {
+      config = this.mergeConfig(this.toRequestConfig(requestConfig), {
+        path: artworkUrl
+      })
+    }
+    if (artworkConfig) {
+      config = this.mergeConfig(config, this.toRequestConfig(artworkConfig))
+    }
 
     const resolvedUri = BrowserPathHelper.buildUrl(
       config.baseUrl,
@@ -210,25 +252,30 @@ export const RequestConfigBuilder = {
   /**
    * Resolves an artwork URL asynchronously with full Track access.
    * Supports resolve and transform callbacks from ArtworkRequestConfig.
-   * Matches Android's CoilBitmapLoader.transformArtworkUrlForTrack() behavior.
+   * Matches the native platforms' BrowserManager resolveArtworkUrl behavior.
    *
    * The resolution order is:
+   * 0. Apply the shared `request` layer (its transform runs for artwork too)
    * 1. If resolve callback exists, call it with the track to get per-track config
    * 2. Merge base config + resolved config
    * 3. Apply imageQueryParams if context has dimensions
    * 4. Apply transform callback if present
    *
    * @param track The track to resolve artwork for (full Track object)
+   * @param requestConfig The shared request configuration (applied first)
    * @param artworkConfig The artwork request configuration
    * @param imageContext Optional image context with size hints (width/height)
    * @returns ImageSource with resolved URI, or undefined if no artwork
    */
   async resolveArtworkSourceAsync(
     track: Track,
+    requestConfig: TransformableRequestConfig | undefined,
     artworkConfig: ArtworkRequestConfig | undefined,
     imageContext?: ImageContext
   ): Promise<ImageSource | undefined> {
-    const artworkUrl = track.artwork
+    // Collapses a per-appearance pair to one URL: this pipeline produces a
+    // single `ImageSource`, and the web fallback renders one <Image>.
+    const artworkUrl = resolveArtworkUrl(track.artwork)
 
     // If no config and no track.artwork, nothing to transform
     if (!artworkConfig && !artworkUrl) {
@@ -241,18 +288,35 @@ export const RequestConfigBuilder = {
     }
 
     try {
-      // Step 1: Call resolve callback if provided to get per-track config
+      // Step 0: Apply the shared request layer, with track.artwork as the path.
+      // Its transform (if any) runs for artwork too — e.g. a dynamic baseUrl.
+      const baseConfig = await this.applyLayer(
+        { path: artworkUrl },
+        requestConfig
+      )
+
+      // Step 1: Per-track resolution — async `resolve` first, then `resolveSync`
+      // merged over it (mirrors native).
       let resolvedConfig: RequestConfig | undefined
       if (artworkConfig.resolve) {
         resolvedConfig = await artworkConfig.resolve(track)
-        // If resolve callback returned null/undefined, that means no artwork
-        if (!resolvedConfig && artworkUrl === undefined) {
-          return undefined
-        }
+      }
+      if (artworkConfig.resolveSync) {
+        const r = artworkConfig.resolveSync(track)
+        resolvedConfig = resolvedConfig
+          ? this.mergeConfig(resolvedConfig, r)
+          : r
+      }
+      // If a resolver ran but produced nothing and there's no artwork URL, no artwork
+      if (
+        (artworkConfig.resolve || artworkConfig.resolveSync) &&
+        !resolvedConfig &&
+        artworkUrl === undefined
+      ) {
+        return undefined
       }
 
       // Step 2: Merge base config + resolved per-track config
-      const baseConfig: RequestConfig = { path: artworkUrl }
       let mergedConfig = this.mergeConfig(
         this.mergeConfig(baseConfig, this.toRequestConfig(artworkConfig)),
         resolvedConfig ?? {}
@@ -265,13 +329,19 @@ export const RequestConfigBuilder = {
         imageContext
       )
 
-      // Step 4: Apply transform callback if present
+      // Step 4: Apply transform — async first, then sync (pipeline)
       if (artworkConfig.transform) {
         mergedConfig = await artworkConfig.transform({
           request: mergedConfig,
           context: imageContext
         })
       }
+      if (artworkConfig.transformSync) {
+        mergedConfig = artworkConfig.transformSync({
+          request: mergedConfig,
+          context: imageContext
+        })
+      }
 
       // Build final URL
       const resolvedUri = BrowserPathHelper.buildUrl(
@@ -299,18 +369,21 @@ export const RequestConfigBuilder = {
    * Matches Android's transformArtworkUrl behavior.
    *
    * @param track The track to transform
+   * @param requestConfig The shared request configuration (static fields only)
    * @param artworkConfig The artwork request configuration
    * @returns Track with artworkSource populated
    */
   transformTrackArtwork(
     track: Track,
+    requestConfig: TransformableRequestConfig | undefined,
     artworkConfig: ArtworkRequestConfig | undefined
   ): Track {
     // If artworkSource is already set, don't override it
     if (track.artworkSource) return track
 
     const artworkSource = this.resolveArtworkSource(
-      track.artwork,
+      resolveArtworkUrl(track.artwork),
+      requestConfig,
       artworkConfig
     )
     if (!artworkSource) return track
@@ -321,22 +394,6 @@ export const RequestConfigBuilder = {
     }
   },
 
-  /**
-   * Transforms artwork URLs for an array of tracks.
-   *
-   * @param tracks Array of tracks to transform
-   * @param artworkConfig The artwork request configuration
-   * @returns Tracks with artworkSource populated
-   */
-  transformTracksArtwork(
-    tracks: Track[],
-    artworkConfig: ArtworkRequestConfig | undefined
-  ): Track[] {
-    return tracks.map((track) =>
-      this.transformTrackArtwork(track, artworkConfig)
-    )
-  },
-
   /**
    * Merges header maps, with override values taking precedence.
    */

package/src/web/playbackErrorKind.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { kindForHttpStatus, playbackErrorKind } from './playbackErrorKind'
+
+const BAD_HTTP_STATUS = 1001
+const TIMEOUT = 1003
+
+describe('kindForHttpStatus', () => {
+  it('maps statuses to kinds', () => {
+    // 404/410 must be checked before the 400-499 arm swallows them.
+    expect(kindForHttpStatus(404)).toBe('not-found')
+    expect(kindForHttpStatus(410)).toBe('not-found')
+    // Range edges.
+    expect(kindForHttpStatus(400)).toBe('rejected')
+    expect(kindForHttpStatus(499)).toBe('rejected')
+    expect(kindForHttpStatus(500)).toBe('server-error')
+    expect(kindForHttpStatus(599)).toBe('server-error')
+    expect(kindForHttpStatus(302)).toBe('unknown')
+    expect(kindForHttpStatus(600)).toBe('unknown')
+  })
+})
+
+describe('playbackErrorKind', () => {
+  it('reports offline regardless of the code', () => {
+    expect(playbackErrorKind(BAD_HTTP_STATUS, 404, false)).toBe('offline')
+  })
+
+  it('uses the HTTP status Shaka carries in data[1]', () => {
+    expect(playbackErrorKind(BAD_HTTP_STATUS, 503)).toBe('server-error')
+  })
+
+  it('falls back to the category when no status was reported', () => {
+    // BAD_HTTP_STATUS is category 1, which is not one of the unplayable
+    // categories — without a status there is nothing to classify.
+    expect(playbackErrorKind(BAD_HTTP_STATUS)).toBe('unknown')
+  })
+
+  it('treats network timeouts as unreachable', () => {
+    expect(playbackErrorKind(TIMEOUT)).toBe('unreachable')
+  })
+
+  it('treats media, manifest and streaming failures as unplayable', () => {
+    expect(playbackErrorKind(3016)).toBe('unplayable') // MEDIA
+    expect(playbackErrorKind(4032)).toBe('unplayable') // MANIFEST
+    expect(playbackErrorKind(5006)).toBe('unplayable') // STREAMING
+  })
+
+  it('treats DRM failures as rejected', () => {
+    expect(playbackErrorKind(6001)).toBe('rejected')
+  })
+
+  it('leaves codes that name no cause unknown', () => {
+    expect(playbackErrorKind(7001)).toBe('unknown') // PLAYER
+    expect(playbackErrorKind(-1)).toBe('unknown') // our own non-Shaka fallback
+  })
+})

package/src/web/playbackErrorKind.ts

@@ -0,0 +1,56 @@
+import type { PlaybackErrorKind } from '../features/errors'
+
+/**
+ * Maps Shaka's error codes onto {@link PlaybackErrorKind}, the same
+ * cross-platform contract iOS derives from AVFoundation and Android from
+ * ExoPlayer.
+ *
+ * Shaka numbers its codes `<category><nnn>`: 1xxx network, 2xxx text, 3xxx
+ * media, 4xxx manifest, 5xxx streaming, 6xxx DRM, 7xxx player.
+ *
+ * As on the native side, codes that name no cause stay `'unknown'` rather than
+ * being guessed into a friendlier bucket.
+ */
+
+const BAD_HTTP_STATUS = 1001
+const HTTP_ERROR = 1002
+const TIMEOUT = 1003
+const ATTEMPTS_EXHAUSTED = 1010
+
+export function kindForHttpStatus(status: number): PlaybackErrorKind {
+  if (status === 404 || status === 410) return 'not-found'
+  if (status >= 500 && status <= 599) return 'server-error'
+  // Every other 4xx is the server refusing us — auth, geo-blocking, a rate
+  // limit. All of them mean "you can't have this stream", not "retry".
+  if (status >= 400 && status <= 499) return 'rejected'
+  return 'unknown'
+}
+
+/**
+ * @param code - a `shaka.util.Error.Code`
+ * @param httpStatus - the status Shaka reported for `BAD_HTTP_STATUS`, which it
+ *   carries in `error.data[1]`
+ * @param online - `navigator.onLine`. Shaka's codes cannot tell a dead station
+ *   from a dead connection; only the browser can.
+ */
+export function playbackErrorKind(
+  code: number,
+  httpStatus?: number,
+  online = true
+): PlaybackErrorKind {
+  if (!online) return 'offline'
+  if (code === BAD_HTTP_STATUS && httpStatus !== undefined) {
+    return kindForHttpStatus(httpStatus)
+  }
+  if (code === HTTP_ERROR || code === TIMEOUT || code === ATTEMPTS_EXHAUSTED) {
+    return 'unreachable'
+  }
+  const category = Math.floor(code / 1000)
+  // Media, manifest and streaming failures all mean the same thing to a
+  // listener: it arrived, and it is not playable.
+  if (category === 2 || category === 3 || category === 4 || category === 5) {
+    return 'unplayable'
+  }
+  if (category === 6) return 'rejected'
+  return 'unknown'
+}