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

package/src/features/browser.ts

@@ -1,207 +1,14 @@
-import type {
-  BrowserConfiguration,
-  BrowserSource,
-  BrowserSourceCallback,
-  ResolvedTrack,
-  RouteConfig,
-  SearchSource,
-  SearchSourceCallback,
-  TabsSource,
-  Track,
-  TransformableRequestConfig
-} from '../types'
-import type {
-  NativeBrowserConfiguration,
-  NativeRouteEntry
-} from '../types/browser-native'
+import type { BrowserConfiguration, ResolvedTrack, Track } from '../types'
 import { nativeBrowser } from '../native'
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+import {
+  SEARCH_ROUTE_PATH,
+  toNativeConfig,
+  validateBrowserConfiguration
+} from './browser-config'
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Configuration Transformation
-// ─────────────────────────────────────────────────────────────────────────────
-
-function isCallback(
-  source: unknown
-): source is (...args: unknown[]) => unknown {
-  return typeof source === 'function'
-}
-
-function isTransformableRequestConfig(
-  source: unknown
-): source is TransformableRequestConfig {
-  if (typeof source !== 'object' || source === null) return false
-  const obj = source as Record<string, unknown>
-  // Has request config properties (not a ResolvedTrack which has 'title')
-  return (
-    'baseUrl' in obj ||
-    'path' in obj ||
-    'headers' in obj ||
-    'query' in obj ||
-    'transform' in obj
-  )
-}
-
-function isRouteConfig(source: unknown): source is RouteConfig {
-  if (typeof source !== 'object' || source === null) return false
-  const obj = source as Record<string, unknown>
-  // RouteConfig has browse/media/artwork properties at the top level
-  return 'browse' in obj || ('media' in obj && !('baseUrl' in obj))
-}
-
-function flattenBrowseSource(source: BrowserSource | undefined): {
-  browseCallback?: NativeRouteEntry['browseCallback']
-  browseConfig?: NativeRouteEntry['browseConfig']
-  browseStatic?: NativeRouteEntry['browseStatic']
-} {
-  if (!source) return {}
-  if (isCallback(source))
-    return { browseCallback: source as NativeRouteEntry['browseCallback'] }
-  if (isTransformableRequestConfig(source))
-    return { browseConfig: source as NativeRouteEntry['browseConfig'] }
-  return { browseStatic: source as NativeRouteEntry['browseStatic'] }
-}
-
-/**
- * Converts a SearchSource to a NativeRouteEntry for the __search__ path.
- */
-function searchSourceToRouteEntry(source: SearchSource): NativeRouteEntry {
-  if (isCallback(source)) {
-    return {
-      path: SEARCH_ROUTE_PATH,
-      searchCallback: source as SearchSourceCallback
-    }
-  }
-  return {
-    path: SEARCH_ROUTE_PATH,
-    searchConfig: source as TransformableRequestConfig
-  }
-}
-
-/**
- * Wraps a Track[] into a ResolvedTrack for tabs.
- * Tabs are represented as a special route that returns children.
- */
-function wrapTracksAsResolvedTrack(tracks: Track[]): ResolvedTrack {
-  return {
-    url: TABS_ROUTE_PATH,
-    title: 'Tabs',
-    children: tracks
-  }
-}
-
-/**
- * Converts a TabsSource to a NativeRouteEntry for the __tabs__ path.
- * Track[] is wrapped in ResolvedTrack, callbacks are wrapped to return ResolvedTrack.
- */
-function tabsSourceToRouteEntry(source: TabsSource): NativeRouteEntry {
-  if (Array.isArray(source)) {
-    // Static Track[] - wrap as ResolvedTrack
-    return {
-      path: TABS_ROUTE_PATH,
-      browseStatic: wrapTracksAsResolvedTrack(source)
-    }
-  }
-
-  if (isCallback(source)) {
-    // Callback returning Track[] - wrap to return ResolvedTrack
-    const wrappedCallback: BrowserSourceCallback = async () => {
-      const tracks = await source()
-      return wrapTracksAsResolvedTrack(tracks)
-    }
-    return {
-      path: TABS_ROUTE_PATH,
-      browseCallback: wrappedCallback
-    }
-  }
-
-  // TransformableRequestConfig - native will handle wrapping the response
-  return {
-    path: TABS_ROUTE_PATH,
-    browseConfig: source
-  }
-}
-
-function flattenRouteEntry(
-  path: string,
-  source: BrowserSource | RouteConfig
-): NativeRouteEntry {
-  if (isRouteConfig(source)) {
-    return {
-      path,
-      ...flattenBrowseSource(source.browse),
-      media: source.media,
-      artwork: source.artwork
-    }
-  }
-  return { path, ...flattenBrowseSource(source) }
-}
-
-/** Internal path used for the default/root browse source */
-const DEFAULT_ROUTE_PATH = '__default__'
-
-/** Internal path used for navigation tabs */
-const TABS_ROUTE_PATH = '__tabs__'
-
-/** Internal path used for search */
-const SEARCH_ROUTE_PATH = '__search__'
-
-function flattenRoutes(
-  routes: Record<string, BrowserSource | RouteConfig> | undefined,
-  rootBrowse: BrowserSource | undefined,
-  tabs: TabsSource | undefined,
-  search: SearchSource | undefined
-): NativeRouteEntry[] | undefined {
-  const entries: NativeRouteEntry[] = []
-
-  // Add explicit routes
-  if (routes) {
-    for (const [path, source] of Object.entries(routes)) {
-      entries.push(flattenRouteEntry(path, source))
-    }
-  }
-
-  // Add root browse as default fallback
-  if (rootBrowse) {
-    entries.push(flattenRouteEntry(DEFAULT_ROUTE_PATH, rootBrowse))
-  }
-
-  // Add tabs as special route
-  if (tabs) {
-    entries.push(tabsSourceToRouteEntry(tabs))
-  }
-
-  // Add search as special route
-  if (search) {
-    entries.push(searchSourceToRouteEntry(search))
-  }
-
-  return entries.length > 0 ? entries : undefined
-}
-
-function toNativeConfig(
-  config: BrowserConfiguration
-): NativeBrowserConfiguration {
-  return {
-    path: config.path,
-    request: config.request,
-    media: config.media,
-    artwork: config.artwork,
-    routes: flattenRoutes(
-      config.routes,
-      config.browse,
-      config.tabs,
-      config.search
-    ),
-    singleTrack: config.singleTrack,
-    handleTrackLoad: config.handleTrackLoad,
-    androidControllerOfflineError: config.androidControllerOfflineError,
-    carPlayUpNextButton: config.carPlayUpNextButton,
-    carPlayNowPlayingButtons: config.carPlayNowPlayingButtons,
-    formatNavigationError: config.formatNavigationError
-  }
-}
+let currentConfiguration: BrowserConfiguration | undefined
 
 /**
  * Configures the browser with routes, tabs, and other settings.
@@ -210,13 +17,30 @@ function toNativeConfig(
  * - Android Auto / CarPlay browsing integration
  * - Playback of browsable tracks via navigate()
  *
+ * Calling this again REPLACES the entire configuration (no merging) and
+ * re-runs initial navigation — external browse UIs such as CarPlay reset to
+ * the first tab. For values that change at runtime (base URL, locale, auth
+ * token), don't reconfigure: read them inside a `request`/`browse` resolver
+ * or a `transform`, and call {@link invalidateAllContent} so every surface
+ * re-fetches in place.
+ *
  * @param configuration - Browser configuration including routes, tabs, media config, etc.
  *
  * @example
  * ```ts
  * configureBrowser({
+ *   request: { baseUrl: 'https://api.example.com' },
  *   routes: {
- *     '/albums/:id': { path: '/api/albums/:id' }
+ *     // `{id}` is a route parameter — see the `routes` docs for matching rules.
+ *     '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
+ *     // Remapping a browse path to a different API path requires a transform;
+ *     // a static `path` on a request config does NOT rewrite the path.
+ *     '/artists/{id}': {
+ *       transformSync: (request, routeParams) => ({
+ *         ...request,
+ *         path: `/api/v2/artists/${routeParams?.id}`
+ *       })
+ *     }
  *   },
  *   tabs: [
  *     { title: 'Home', url: '/' },
@@ -226,9 +50,26 @@ function toNativeConfig(
  * ```
  */
 export function configureBrowser(configuration: BrowserConfiguration): void {
+  // __DEV__ is a React Native global; absent under plain node (vitest).
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    validateBrowserConfiguration(configuration)
+  }
+  currentConfiguration = configuration
   nativeBrowser.configuration = toNativeConfig(configuration)
 }
 
+/**
+ * Returns the configuration last passed to {@link configureBrowser}, in its
+ * original public shape (the native getter exposes only the lowered internal
+ * form). `undefined` until the browser is configured.
+ *
+ * Treat the returned object as read-only: it is the live reference, and
+ * mutating it does NOT reconfigure the browser — call configureBrowser again.
+ */
+export function getBrowserConfiguration(): BrowserConfiguration | undefined {
+  return currentConfiguration
+}
+
 export function navigate(pathOrTrack: string | Track) {
   if (typeof pathOrTrack === 'string') {
     return nativeBrowser.navigatePath(pathOrTrack)
@@ -288,6 +129,22 @@ export const notifyContentChanged = (path: string): void => {
   nativeBrowser.notifyContentChanged(path)
 }
 
+/**
+ * Invalidates all cached browse content and refreshes every currently-displayed
+ * browse surface. Use when something app-wide changed (locale switch, sign-out,
+ * etc.) and every browse path should re-fetch from its route handler — unlike
+ * {@link notifyContentChanged}, which targets a single path.
+ *
+ * @example
+ * ```ts
+ * // After the user changes the app language
+ * invalidateAllContent()
+ * ```
+ */
+export const invalidateAllContent = (): void => {
+  nativeBrowser.invalidateAllContent()
+}
+
 /**
  * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
  */
@@ -312,5 +169,5 @@ export function hasSearch(): boolean {
  * ```
  */
 export async function search(query: string): Promise<Track[]> {
-  return nativeBrowser.onSearch(query)
+  return nativeBrowser.search(query)
 }

package/src/features/carConnection.ts

@@ -0,0 +1,36 @@
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// MARK: - Getters
+
+/**
+ * Whether a car is currently connected: a CarPlay scene on iOS, an
+ * Android Auto / Android Automotive connection on Android (via the
+ * androidx.car.app CarConnection provider). Always false on web.
+ */
+export function isCarConnected(): boolean {
+  return nativeBrowser.isCarConnected()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to car connection changes (CarPlay on iOS, Android Auto /
+ * Android Automotive on Android). Never fires on web.
+ * @param callback - Called with the new connection state
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ */
+export const onCarConnectedChanged = NativeUpdatedValue.emitterize<boolean>(
+  (cb) => (nativeBrowser.onCarConnectedChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether a car is connected and updates on changes
+ * (always false on web).
+ */
+export function useCarConnected(): boolean {
+  return useNativeUpdatedValue(isCarConnected, onCarConnectedChanged)
+}

package/src/features/equalizer.ts

@@ -46,7 +46,7 @@ export function setEqualizerLevels(levels: number[]): void {
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onEqualizerChanged =
   NativeUpdatedValue.emitterize<EqualizerSettings>(

package/src/features/errors.ts

@@ -6,13 +6,73 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
 // Re-export for Nitro spec
 export type { FormattedNavigationError } from '../types/browser'
 
+/**
+ * Normalized, cross-platform classification of a playback failure.
+ *
+ * Both platforms map their native failure onto this set, so consumers can
+ * branch on it without knowing whether the error came from AVFoundation or
+ * ExoPlayer. Use this — not `code` — for anything user-visible.
+ *
+ * - `'offline'` - The device had no network connection at the moment of
+ *   failure. The stream itself may be fine.
+ * - `'unreachable'` - The stream host could not be reached: DNS failure,
+ *   connection refused, timed out, or the connection dropped while loading.
+ * - `'not-found'` - The server said this stream is gone (HTTP 404 / 410).
+ *   Retrying will not help; the station is dead.
+ * - `'rejected'` - The server refused the request (HTTP 401 / 403), e.g.
+ *   geo-blocking or an expired token.
+ * - `'server-error'` - The server responded with 5xx. Usually transient.
+ * - `'unplayable'` - The stream was fetched but cannot be played: unknown
+ *   container, unsupported codec, or a decoder failure.
+ * - `'stalled'` - Playback had started and then stopped, and the player
+ *   exhausted its recovery budget without recovering.
+ * - `'unknown'` - The failure could not be classified. Inspect `code`.
+ */
+export type PlaybackErrorKind =
+  | 'offline'
+  | 'unreachable'
+  | 'not-found'
+  | 'rejected'
+  | 'server-error'
+  | 'unplayable'
+  | 'stalled'
+  | 'unknown'
+
 export type PlaybackError = {
+  /** Normalized classification. Branch on this, not on `code`. */
+  kind: PlaybackErrorKind
+  /**
+   * The raw native failure identifier, for diagnostics and telemetry only.
+   * Platform-specific and unstable: loader cases on iOS
+   * (`failed-to-load`, `playback-failed`, …), lower-cased ExoPlayer error
+   * names on Android (`io-bad-http-status`, `parsing-container-malformed`, …).
+   */
   code: string
   message: string
+  /** HTTP status code, when the failure came from an HTTP response. */
+  statusCode?: number
+  /**
+   * True while the player is still retrying this failure in the background.
+   *
+   * A retrying error arrives via `onPlaybackChanged` with the playback state
+   * still `loading`/`buffering` (or `paused`) — show it as advisory ("Stream
+   * unreachable" over a spinner), because playback may yet recover. It clears
+   * (the next `Playback` carries no error) once data flows again, and hardens
+   * into a terminal error (state `error`, `retrying` absent) when the retry
+   * budget runs out. Absent when retry is disabled: every error is then
+   * terminal. Native platforms only — the web implementation has no automatic
+   * retry, so its errors are always terminal.
+   */
+  retrying?: boolean
 }
 
 /**
  * Emitted when a playback error occurs.
+ *
+ * Terminal errors only: this fires on both edges of the `error` state —
+ * entering it (with the error) and leaving it (with `error` undefined).
+ * Errors the player is still retrying (`retrying: true`) are surfaced through
+ * `onPlaybackChanged` instead, attached to the `loading`/`buffering` state.
  */
 export interface PlaybackErrorEvent {
   error?: PlaybackError
@@ -29,6 +89,10 @@ export interface PlaybackErrorEvent {
  * - `'callback-error'` - The browse callback returned an error (e.g., `{ error: 'message' }`).
  *   Use this for business logic errors like authentication failures or subscription requirements.
  * - `'unknown-error'` - An unexpected error occurred (e.g., invalid configuration).
+ * - `'empty-content'` - The path resolved successfully but the container has no children (e.g. an
+ *   empty Favorites tab, a search with no results).
+ * - `'timeout'` - The resolve did not complete within the allotted time (a stalled request or
+ *   unresponsive bridge). Surfaced on External surfaces that render their own browse list.
  */
 export type NavigationErrorType =
   | 'content-not-found'
@@ -36,6 +100,8 @@ export type NavigationErrorType =
   | 'http-error'
   | 'callback-error'
   | 'unknown-error'
+  | 'empty-content'
+  | 'timeout'
 
 export type NavigationError = {
   code: NavigationErrorType
@@ -68,7 +134,7 @@ export function getPlaybackError(): PlaybackError | undefined {
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackError =
   NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
@@ -99,7 +165,7 @@ export function getNavigationError(): NavigationError | undefined {
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNavigationError =
   NativeUpdatedValue.emitterize<NavigationErrorEvent>(
@@ -132,7 +198,7 @@ export function getFormattedNavigationError():
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
   FormattedNavigationError | undefined
@@ -142,7 +208,7 @@ export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
  * Hook that returns the current navigation error formatted for display.
  *
  * Native formats the error using the `formatNavigationError` callback configured
- * in {@link BrowserConfiguration}, or falls back to default English messages.
+ * in `BrowserConfiguration`, or falls back to default English messages.
  *
  * The same formatted error is used by CarPlay and Android Auto error dialogs,
  * ensuring consistent error presentation across your app and external controllers.
@@ -183,7 +249,7 @@ export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
  * })
  * ```
  *
- * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
+ * @see `BrowserConfiguration.formatNavigationError` - Configure custom error formatting
  * @see {@link useNavigationError} - Access the raw error with code and status details
  */
 export function useFormattedNavigationError():

package/src/features/favorites.ts

@@ -82,7 +82,7 @@ export interface FavoriteChangedEvent {
  * The native side has already updated the track's favorite state and UI.
  *
  * @param callback - Called with the track and its new favorite state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  *
  * @example
  * ```ts

package/src/features/gate.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../native', () => ({ nativeBrowser: {} }))
+
+import { nativeBrowser } from '../native'
+import { setGate, clearGate } from './gate'
+
+const chrome = { title: 'T', message: 'M' }
+
+beforeEach(() => {
+  ;(nativeBrowser as any).setGate = vi.fn()
+  ;(nativeBrowser as any).clearGate = vi.fn()
+})
+
+describe('setGate', () => {
+  test('setGate(gate) → chrome + hasResolver false', () => {
+    setGate(chrome)
+    expect(nativeBrowser.setGate).toHaveBeenCalledWith(chrome, false)
+  })
+
+  test('setGate(gate, resolve) → chrome + hasResolver true', () => {
+    setGate(chrome, () => true)
+    expect(nativeBrowser.setGate).toHaveBeenCalledWith(chrome, true)
+  })
+
+  test('setGate(resolve) → undefined chrome + hasResolver true', () => {
+    setGate(() => false)
+    expect(nativeBrowser.setGate).toHaveBeenCalledWith(undefined, true)
+  })
+})
+
+describe('resolveGate (native→JS bridge)', () => {
+  test('resolver true → gated, no override', async () => {
+    setGate(chrome, () => true)
+    expect(
+      await (nativeBrowser as any).resolveGate({ reason: 'browse', path: '/x' })
+    ).toEqual({ gated: true })
+  })
+
+  test('resolver false → not gated', async () => {
+    setGate(chrome, () => false)
+    expect(
+      await (nativeBrowser as any).resolveGate({ reason: 'browse', path: '/x' })
+    ).toEqual({ gated: false })
+  })
+
+  test('resolver Gate → gated + override chrome', async () => {
+    const override = { title: 'O' }
+    setGate(chrome, () => override)
+    expect(
+      await (nativeBrowser as any).resolveGate({
+        reason: 'search',
+        search: { query: 'q' }
+      })
+    ).toEqual({ gated: true, gate: override })
+  })
+
+  test('no resolver (static) → every request gated', async () => {
+    setGate(chrome)
+    expect(
+      await (nativeBrowser as any).resolveGate({ reason: 'browse', path: '/x' })
+    ).toEqual({ gated: true })
+  })
+})
+
+describe('clearGate', () => {
+  test('clears native gate state', () => {
+    setGate(chrome, () => false)
+    clearGate()
+    expect(nativeBrowser.clearGate).toHaveBeenCalled()
+  })
+})