@5stones/react-native-audio-browser 0.1.0

package/src/features/battery.ts

@@ -0,0 +1,176 @@
+/**
+ * Battery optimization status and warning handling for Android 12+ foreground service restrictions.
+ *
+ * When an external controller (Bluetooth, car head unit) tries to resume playback while the app
+ * is killed and battery restrictions are in place, Android 12+ blocks the foreground service start.
+ * This module exposes APIs to detect this condition and guide users to fix their settings.
+ */
+
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// MARK: - Types
+
+/**
+ * Battery optimization status.
+ *
+ * - `unrestricted`: App can run freely in background. User explicitly allowed it.
+ * - `optimized`: System may limit background work (Doze, App Standby). Default state.
+ * - `restricted`: User or system severely limited background. Services blocked.
+ */
+export type BatteryOptimizationStatus =
+  | 'unrestricted'
+  | 'optimized'
+  | 'restricted'
+
+/**
+ * Event fired when battery warning pending state changes.
+ */
+export type BatteryWarningPendingChangedEvent = {
+  pending: boolean
+}
+
+/**
+ * Event fired when battery optimization status changes.
+ */
+export type BatteryOptimizationStatusChangedEvent = {
+  status: BatteryOptimizationStatus
+}
+
+// MARK: - Getters
+
+/**
+ * Check if a battery warning is pending (Android only).
+ * Returns true if a foreground service start was blocked and the user hasn't dismissed
+ * the warning or fixed their battery settings.
+ * Auto-clears when battery status becomes unrestricted.
+ * @returns true if warning is pending, always false on iOS
+ */
+export function getBatteryWarningPending(): boolean {
+  return nativeBrowser.getBatteryWarningPending()
+}
+
+/**
+ * Get the current battery optimization status (Android only).
+ * Also fires onBatteryOptimizationStatusChanged if status changed since last call.
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export function getBatteryOptimizationStatus(): BatteryOptimizationStatus {
+  return nativeBrowser.getBatteryOptimizationStatus()
+}
+
+// MARK: - Actions
+
+/**
+ * Dismiss the battery warning without fixing settings (Android only).
+ * Call this when the user chooses to ignore the warning.
+ * No-op on iOS.
+ */
+export function dismissBatteryWarning(): void {
+  nativeBrowser.dismissBatteryWarning()
+}
+
+/**
+ * Open the system battery settings for this app (Android only).
+ * No-op on iOS.
+ */
+export function openBatterySettings(): void {
+  nativeBrowser.openBatterySettings()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to battery warning pending state changes (Android only).
+ * Fires when: failure occurs (true), dismissBatteryWarning() called (false),
+ * or status becomes unrestricted (false).
+ * Never fires on iOS.
+ */
+export const onBatteryWarningPendingChanged =
+  NativeUpdatedValue.emitterize<BatteryWarningPendingChangedEvent>(
+    (cb) => (nativeBrowser.onBatteryWarningPendingChanged = cb)
+  )
+
+/**
+ * Subscribes to battery optimization status changes (Android only).
+ * Fires when user returns from settings with a different status.
+ * Never fires on iOS.
+ */
+export const onBatteryOptimizationStatusChanged =
+  NativeUpdatedValue.emitterize<BatteryOptimizationStatusChangedEvent>(
+    (cb) => (nativeBrowser.onBatteryOptimizationStatusChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether a battery warning is pending and updates when it changes (Android only).
+ * @returns true if warning is pending, always false on iOS
+ */
+export function useBatteryWarningPending(): boolean {
+  return useNativeUpdatedValue(
+    getBatteryWarningPending,
+    onBatteryWarningPendingChanged,
+    'pending'
+  )
+}
+
+/**
+ * Hook that returns the current battery optimization status and updates when it changes (Android only).
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export function useBatteryOptimizationStatus(): BatteryOptimizationStatus {
+  return useNativeUpdatedValue(
+    getBatteryOptimizationStatus,
+    onBatteryOptimizationStatusChanged,
+    'status'
+  )
+}
+
+/**
+ * Return type for useBatteryWarning hook.
+ */
+export interface BatteryWarning {
+  /** Whether a battery warning is pending */
+  pending: boolean
+  /** Current battery optimization status */
+  status: BatteryOptimizationStatus
+  /** Dismiss the warning without changing settings */
+  dismiss: () => void
+  /** Open system battery settings for this app */
+  openSettings: () => void
+}
+
+/**
+ * Meta hook that bundles all battery warning state and actions (Android only).
+ * Use this for a complete battery warning UI implementation.
+ *
+ * @example
+ * ```tsx
+ * function BatteryWarningBanner() {
+ *   const { pending, status, dismiss, openSettings } = useBatteryWarning()
+ *
+ *   if (!pending) return null
+ *
+ *   return (
+ *     <View>
+ *       <Text>Battery status: {status}</Text>
+ *       <Button onPress={openSettings} title="Fix" />
+ *       <Button onPress={dismiss} title="Dismiss" />
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export function useBatteryWarning(): BatteryWarning {
+  const pending = useBatteryWarningPending()
+  const status = useBatteryOptimizationStatus()
+
+  return {
+    pending,
+    status,
+    dismiss: dismissBatteryWarning,
+    openSettings: openBatterySettings
+  }
+}

package/src/features/browser.ts

@@ -0,0 +1,315 @@
+import { nativeBrowser } from '../native'
+import type {
+  BrowserConfiguration,
+  BrowserSource,
+  BrowserSourceCallback,
+  ResolvedTrack,
+  RouteConfig,
+  SearchSource,
+  SearchSourceCallback,
+  TabsSource,
+  Track,
+  TransformableRequestConfig
+} from '../types'
+import type {
+  NativeBrowserConfiguration,
+  NativeRouteEntry
+} from '../types/browser-native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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,
+    androidControllerOfflineError: config.androidControllerOfflineError,
+    carPlayUpNextButton: config.carPlayUpNextButton,
+    carPlayNowPlayingButtons: config.carPlayNowPlayingButtons,
+    formatNavigationError: config.formatNavigationError
+  }
+}
+
+/**
+ * Configures the browser with routes, tabs, and other settings.
+ * Also registers the browser with the player to enable:
+ * - Media URL transformation for authenticated playback
+ * - Android Auto / CarPlay browsing integration
+ * - Playback of browsable tracks via navigate()
+ *
+ * @param configuration - Browser configuration including routes, tabs, media config, etc.
+ *
+ * @example
+ * ```ts
+ * configureBrowser({
+ *   routes: {
+ *     '/albums/:id': { path: '/api/albums/:id' }
+ *   },
+ *   tabs: [
+ *     { title: 'Home', url: '/' },
+ *     { title: 'Search', url: '/search' }
+ *   ]
+ * })
+ * ```
+ */
+export function configureBrowser(configuration: BrowserConfiguration): void {
+  nativeBrowser.configuration = toNativeConfig(configuration)
+}
+
+export function navigate(pathOrTrack: string | Track) {
+  if (typeof pathOrTrack === 'string') {
+    return nativeBrowser.navigatePath(pathOrTrack)
+  } else {
+    return nativeBrowser.navigateTrack(pathOrTrack)
+  }
+}
+
+export function getPath() {
+  return nativeBrowser.path
+}
+
+export const onPathChanged = NativeUpdatedValue.emitterize<string | undefined>(
+  (cb) => (nativeBrowser.onPathChanged = cb)
+)
+
+export function usePath(): string | undefined {
+  return useNativeUpdatedValue(getPath, onPathChanged)
+}
+
+export function getContent(): ResolvedTrack | undefined {
+  return nativeBrowser.getContent()
+}
+
+export const onContentChanged = NativeUpdatedValue.emitterize<
+  ResolvedTrack | undefined
+>((cb) => (nativeBrowser.onContentChanged = cb))
+
+export function useContent(): ResolvedTrack | undefined {
+  return useNativeUpdatedValue(getContent, onContentChanged)
+}
+export function getTabs(): Track[] | undefined {
+  return nativeBrowser.tabs
+}
+
+export const onTabsChanged = NativeUpdatedValue.emitterize<Track[] | undefined>(
+  (cb) => (nativeBrowser.onTabsChanged = cb)
+)
+
+export function useTabs(): Track[] | undefined {
+  return useNativeUpdatedValue(getTabs, onTabsChanged)
+}
+
+/**
+ * Notifies external media controllers (Android Auto, CarPlay) that content
+ * at the specified path has changed and should be refreshed.
+ *
+ * @param path - The path where content has changed (e.g., '/favorites')
+ *
+ * @example
+ * ```ts
+ * // After adding a track to favorites
+ * notifyContentChanged('/favorites')
+ * ```
+ */
+export const notifyContentChanged = (path: string): void => {
+  nativeBrowser.notifyContentChanged(path)
+}
+
+/**
+ * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
+ */
+export function hasSearch(): boolean {
+  const config = nativeBrowser.configuration
+  const searchRoute = config.routes?.find((r) => r.path === SEARCH_ROUTE_PATH)
+  return !!(searchRoute?.searchCallback || searchRoute?.searchConfig)
+}
+
+/**
+ * Searches for tracks using the configured search source.
+ *
+ * @param query - The search query string
+ * @returns Promise resolving to an array of matching tracks
+ *
+ * @see {@link configureBrowser}
+ *
+ * @example
+ * ```ts
+ * const results = await search('jazz')
+ * console.log(`Found ${results.length} tracks`)
+ * ```
+ */
+export async function search(query: string): Promise<Track[]> {
+  return nativeBrowser.onSearch(query)
+}

package/src/features/equalizer.ts

@@ -0,0 +1,64 @@
+import { nativeBrowser } from '../native'
+import type { EqualizerSettings } from '../specs/audio-browser.nitro'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+export type { EqualizerSettings }
+
+// MARK: - Getters
+
+/**
+ * Gets the current equalizer settings (Android only).
+ * @returns Equalizer settings, or undefined if not available
+ */
+export function getEqualizerSettings(): EqualizerSettings | undefined {
+  return nativeBrowser.getEqualizerSettings()
+}
+
+// MARK: - Setters
+
+/**
+ * Enables or disables the equalizer (Android only).
+ * @param enabled - Whether to enable the equalizer
+ */
+export function setEqualizerEnabled(enabled: boolean): void {
+  nativeBrowser.setEqualizerEnabled(enabled)
+}
+
+/**
+ * Sets the equalizer to a preset (Android only).
+ * @param preset - The name of the preset to apply
+ */
+export function setEqualizerPreset(preset: string): void {
+  nativeBrowser.setEqualizerPreset(preset)
+}
+
+/**
+ * Sets custom equalizer band levels (Android only).
+ * @param levels - Array of level values for each band (in millibels)
+ */
+export function setEqualizerLevels(levels: number[]): void {
+  nativeBrowser.setEqualizerLevels(levels)
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to equalizer settings changes (Android only).
+ * @param callback - Called when equalizer settings change
+ * @returns Cleanup function to unsubscribe
+ */
+export const onEqualizerChanged =
+  NativeUpdatedValue.emitterize<EqualizerSettings>(
+    (cb) => (nativeBrowser.onEqualizerChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current equalizer settings and updates when they change (Android only).
+ * @returns Current equalizer settings, or undefined if not available
+ */
+export function useEqualizerSettings(): EqualizerSettings | undefined {
+  return useNativeUpdatedValue(getEqualizerSettings, onEqualizerChanged)
+}