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

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: ... })`.
  */

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 Cleanup function to unsubscribe
+ */
+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/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
@@ -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/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()
+  })
+})

package/src/features/gate.ts

@@ -0,0 +1,155 @@
+import type { SearchParams } from '../types/browser'
+import { nativeBrowser } from '../native'
+import { LazyNativeEmitter } from '../utils/LazyNativeEmitter'
+
+// MARK: - Wire types (cross the Nitro bridge; native↔JS)
+
+/** Discriminant for gate requests and events. */
+export type GateReason = 'browse' | 'search'
+
+/**
+ * Flat wire struct for a gate request (crosses the Nitro bridge).
+ * Use {@link GateRequest} in consumer-facing code; `gate.ts` converts between them.
+ * @internal
+ */
+export type NativeGateRequest = {
+  reason: GateReason
+  path?: string
+  search?: SearchParams
+}
+
+/**
+ * Wire form of a resolver result (native awaits this from JS).
+ * @internal
+ */
+export type GateDecision = { gated: boolean; gate?: Gate }
+
+/**
+ * Fired once per gated serve (each time the gate chrome is rendered for a
+ * request). This is **not** once per user action: on car surfaces a single
+ * action can serve the gate for several requests at once — e.g. building the
+ * tab bar resolves and serves each gated tab, firing one event per gated tab.
+ * There is no library-side dedup; debounce on the consumer side (e.g. record a
+ * gate-hit at most once per session).
+ */
+export type GateEvent = { reason: GateReason }
+
+// MARK: - Public types (consumer-facing)
+
+/**
+ * A gate's chrome (title and optional message).
+ *
+ * While the gate is active, every browse or search request on car surfaces
+ * (CarPlay, Android Auto) shows this page instead of the real content.
+ * Playback, the queue, and now-playing are unaffected.
+ *
+ * - **CarPlay**: plain centered message page.
+ * - **Android Auto**: one non-playable list tile (message not shown).
+ */
+export type Gate = {
+  /** Headline shown on the gate page. */
+  title: string
+  /**
+   * The explanatory copy under the title. On CarPlay this is the centered
+   * message body; newlines become spaces. Android Auto does not display it.
+   */
+  message?: string
+}
+
+/**
+ * The gate chrome crosses the bridge as-is; this alias marks the wire side.
+ * @internal
+ */
+export type NativeGate = Gate
+
+/**
+ * Describes the request being decided by a {@link GateResolver}.
+ * Discriminated by `kind`: `'browse'` for content navigation, `'search'` for
+ * voice/manual search queries.
+ */
+export type GateRequest =
+  | { kind: 'browse'; path: string }
+  | { kind: 'search'; params: SearchParams }
+
+/**
+ * Decides per request whether to gate.
+ * - Return a {@link Gate} to gate with specific chrome for this request.
+ * - Return `true` to gate using the default chrome (or the built-in fallback).
+ * - Return `false` to allow the request through.
+ */
+export type GateResolver = (request: GateRequest) => Gate | boolean
+
+// MARK: - Internal state
+
+let resolver: GateResolver | undefined
+
+function toPublicRequest(req: NativeGateRequest): GateRequest {
+  switch (req.reason) {
+    case 'browse':
+      return { kind: 'browse', path: req.path ?? '' }
+    case 'search':
+      // req.search is always present on a well-formed search request — the
+      // native wire contract guarantees it for reason:'search'. Assert the
+      // native contract with `!` so we never hand consumer code a SearchParams
+      // with its required `query` field missing.
+      return { kind: 'search', params: req.search! }
+    default: {
+      const _exhaustive: never = req.reason
+      throw new Error(`Unhandled GateReason: ${String(_exhaustive)}`)
+    }
+  }
+}
+
+// Native awaits this per request at a serve site.
+// No resolver → static gate → every request is gated (native applies stored default / built-in).
+nativeBrowser.resolveGate = async (
+  req: NativeGateRequest
+): Promise<GateDecision> => {
+  const result = resolver ? resolver(toPublicRequest(req)) : true
+  if (result === false) return { gated: false }
+  if (result === true) return { gated: true }
+  return { gated: true, gate: result }
+}
+
+// MARK: - Public API
+
+/**
+ * Raises the gate with default chrome, optionally with a per-request resolver.
+ * Calling it again while a gate is already up updates the chrome in place,
+ * keeping the current tab. Note this is **not** fully navigation-preserving: on
+ * some surfaces (CarPlay) any gate change pops pushed navigation back to root,
+ * so a page the user had drilled into is reset to the tab root. Set the gate
+ * before the car connects and it'll be there the moment it does.
+ */
+export function setGate(gate: Gate, resolve?: GateResolver): void
+/**
+ * Raises the gate with a resolver only (no default chrome).
+ * The resolver must return a {@link Gate} or `true` for gated requests;
+ * native uses the built-in fallback chrome when `true` and no default is set.
+ */
+export function setGate(resolve: GateResolver): void
+export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
+  if (typeof a === 'function') {
+    resolver = a
+    nativeBrowser.setGate(undefined, true)
+  } else {
+    resolver = b
+    nativeBrowser.setGate(a, b != null)
+  }
+}
+
+/**
+ * Drops the gate — the real content comes back, and the current tab is kept.
+ */
+export function clearGate(): void {
+  resolver = undefined
+  nativeBrowser.clearGate()
+}
+
+/**
+ * Subscribes to gate events (fired when a request is gated).
+ * @returns Cleanup function to unsubscribe.
+ */
+export const onGate = LazyNativeEmitter.emitterize<GateEvent>(
+  (cb) => (nativeBrowser.onGate = cb)
+)

package/src/features/index.ts

@@ -12,7 +12,9 @@ export * from './playback'
 export * from './player'
 export * from './queue'
 export * from './battery'
+export * from './gate'
 export * from './browser'
+export * from './carConnection'
 export * from './equalizer'
 export * from './errors'
 export * from './favorites'