react-native-audio-browser 0.0.1 → 0.1.0-next.2

package/src/web/browser/BrowserManager.ts

@@ -0,0 +1,699 @@
+import type { NavigationErrorType } from '../../features'
+import type { Track, ResolvedTrack } from '../../types'
+import type { NativeBrowserConfiguration } from '../../types/browser-native'
+import type { HttpClient } from '../http/HttpClient'
+import type { FavoriteManager } from './FavoriteManager'
+import type { NavigationErrorManager } from './NavigationErrorManager'
+import { assertedNotNullish } from '../../utils/validation'
+import { RequestConfigBuilder } from '../http/RequestConfigBuilder'
+import { SimpleRouter } from '../SimpleRouter'
+import { BrowserPathHelper } from '../util/BrowserPathHelper'
+
+/**
+ * Manages browser navigation, route resolution, and content loading.
+ * Coordinates between HTTP client, favorite manager, and error manager.
+ * Matches Android's BrowserManager architecture.
+ */
+export class BrowserManager {
+  private _path: string | undefined
+  private _tabs: Track[] | undefined
+  private _content: ResolvedTrack | undefined
+  private _configuration: NativeBrowserConfiguration = {}
+  private router = new SimpleRouter()
+
+  // Navigation tracking to prevent race conditions (matches Android's @Volatile currentNavigationId)
+  private currentNavigationId = 0
+
+  // Queue expansion tracking (matches Android's queueSourcePath)
+  private _queueSourcePath: string | undefined
+
+  // Event callbacks
+  onPathChanged: (path: string) => void = () => {}
+  onContentChanged: (content: ResolvedTrack | undefined) => void = () => {}
+  onTabsChanged: (tabs: Track[]) => void = () => {}
+
+  constructor(
+    private httpClient: HttpClient,
+    private favoriteManager: FavoriteManager,
+    private navigationErrorManager: NavigationErrorManager
+  ) {}
+
+  /**
+   * Handles navigation errors by extracting error details and setting the navigation error.
+   * Extracts code, message, and statusCode from typed errors, or falls back to generic network error.
+   */
+  private handleNavigationError(error: unknown, path: string): void {
+    if (
+      error &&
+      typeof error === 'object' &&
+      'code' in error &&
+      'message' in error &&
+      typeof error.message === 'string'
+    ) {
+      const navError = error as {
+        code: NavigationErrorType
+        message: string
+        statusCode?: number
+      }
+      this.navigationErrorManager.setNavigationError(
+        navError.code,
+        navError.message,
+        path,
+        navError.statusCode
+      )
+    } else {
+      this.navigationErrorManager.setNavigationError(
+        'network-error',
+        'Failed to load content',
+        path
+      )
+    }
+  }
+
+  /**
+   * Gets the current navigation path.
+   */
+  get path(): string | undefined {
+    return this._path
+  }
+
+  /**
+   * Sets the navigation path and triggers navigation.
+   */
+  set path(value: string | undefined) {
+    if (this.hasValidConfiguration()) {
+      this.navigationErrorManager.clearNavigationError()
+      const pathToNavigate =
+        value ?? this._configuration.path ?? this.getDefaultPath()
+      if (pathToNavigate) {
+        void this.navigate(pathToNavigate)
+      }
+    }
+  }
+
+  /**
+   * Gets the current tabs.
+   */
+  get tabs(): Track[] | undefined {
+    return this._tabs
+  }
+
+  /**
+   * Gets the current content.
+   */
+  get content(): ResolvedTrack | undefined {
+    return this._content
+  }
+
+  /**
+   * Gets the current browser configuration.
+   */
+  get configuration(): NativeBrowserConfiguration {
+    return this._configuration
+  }
+
+  /**
+   * Gets the current queue source path.
+   * Used to track where the current playback queue came from.
+   */
+  get queueSourcePath(): string | undefined {
+    return this._queueSourcePath
+  }
+
+  /**
+   * Sets the queue source path.
+   */
+  set queueSourcePath(value: string | undefined) {
+    this._queueSourcePath = value
+  }
+
+  /**
+   * Sets the browser configuration and triggers initial navigation.
+   */
+  set configuration(value: NativeBrowserConfiguration) {
+    this._configuration = value
+    this.navigationErrorManager.clearNavigationError()
+    this.navigationErrorManager.setFormatCallback(value.formatNavigationError)
+
+    // Update HTTP client base config
+    if (value.request) {
+      this.httpClient.setBaseRequestConfig(value.request)
+    }
+
+    // Determine initial path
+    let initialPath = value.path
+
+    // If no path specified, try to get first tab URL
+    if (!initialPath) {
+      const tabsRoute = value.routes?.find((r) => r.path === '__tabs__')
+      if (tabsRoute?.browseStatic?.children?.[0]?.url) {
+        initialPath = tabsRoute.browseStatic.children[0].url
+      } else {
+        initialPath = '/'
+      }
+    }
+
+    if (initialPath) {
+      void this.navigate(initialPath)
+    }
+  }
+
+  /**
+   * Navigates to a specific path.
+   */
+  async navigatePath(path: string): Promise<void> {
+    this.navigationErrorManager.clearNavigationError()
+    await this.navigate(path)
+  }
+
+  /**
+   * Navigates to a track's URL.
+   */
+  async navigateTrack(track: Track): Promise<void> {
+    this.navigationErrorManager.clearNavigationError()
+    const url = track.url
+    if (!url) {
+      console.warn('Track has no URL to navigate to')
+      return
+    }
+    await this.navigate(url)
+  }
+
+  /**
+   * Notifies that content at a specific path has changed.
+   * If the path is currently displayed, triggers a refresh.
+   */
+  notifyContentChanged(path: string): void {
+    if (this._path === path) {
+      void this.navigate(path)
+    }
+  }
+
+  /**
+   * Main navigation logic.
+   * Resolves content for the given path and updates state.
+   * Uses navigation ID to prevent race conditions (matches Android's BrowserManager.kt:586-607).
+   */
+  private async navigate(path: string): Promise<void> {
+    // Increment navigation ID and capture for this navigation
+    // This prevents stale responses from overwriting newer ones
+    const navigationId = ++this.currentNavigationId
+
+    try {
+      // Update path and clear content immediately to show loading state
+      this._path = path
+      this._content = undefined
+      this.onPathChanged(path)
+      this.onContentChanged(undefined)
+
+      // Resolve content for this path
+      // Search paths use a separate code path that doesn't add contextual URLs
+      // This matches Android where search() bypasses resolve() entirely
+      const isSearchPath = path.startsWith(BrowserPathHelper.SEARCH_PATH_PREFIX)
+      let content = isSearchPath
+        ? await this.resolveSearchContent(path)
+        : await this.resolveContent(path)
+
+      // Check if this is still the current navigation before applying result
+      if (navigationId !== this.currentNavigationId) {
+        // A newer navigation started - discard this result
+        return
+      }
+
+      // Add contextual URLs to non-search content (matches Android behavior where
+      // search() bypasses the resolve() contextual URL logic).
+      // Shallow copy to avoid mutating the original config object (e.g., browseStatic
+      // from routes), which would break search that reads from the same source.
+      if (content?.children && !isSearchPath) {
+        content = {
+          ...content,
+          children: content.children.map((track) => {
+            // If track has src, always add/update contextual URL with current path context
+            // This matches Android's BrowserManager.kt:436-441
+            if (track.src) {
+              const contextualUrl = `${path}?__trackId=${encodeURIComponent(track.src)}`
+              return { ...track, url: contextualUrl }
+            }
+            // Return a shallow copy in attempt to avoid mutating original config objects
+            return { ...track }
+          })
+        }
+      }
+
+      // Hydrate favorites on all children
+      if (content) {
+        content = this.favoriteManager.hydrateChildren(content)
+      }
+
+      // Transform artwork URLs (populates artworkSource)
+      if (content) {
+        content = await this.transformArtworkForContent(content)
+      }
+
+      // Final check before applying result
+      if (navigationId !== this.currentNavigationId) {
+        return
+      }
+
+      this._content = content
+      this.onContentChanged(content)
+
+      // Query and update tabs if configuration has __tabs__ route
+      const tabsRoute = this._configuration.routes?.find(
+        (r) => r.path === '__tabs__'
+      )
+      if (tabsRoute) {
+        const tabs = await this.queryTabs()
+
+        // Check again before applying tabs
+        if (navigationId !== this.currentNavigationId) {
+          return
+        }
+
+        this._tabs = tabs
+        this.onTabsChanged(tabs)
+      }
+    } catch (error) {
+      // Only apply error if this is still the current navigation
+      if (navigationId !== this.currentNavigationId) {
+        return
+      }
+
+      console.error('Navigation failed:', error)
+      this._content = undefined
+      this.onContentChanged(undefined)
+
+      this.handleNavigationError(error, path)
+    }
+  }
+
+  /**
+   * Resolves search content from a search path.
+   * Returns a ResolvedTrack with raw children (no contextual URLs).
+   * Matches Android's BrowserManager.search() which bypasses resolve() entirely.
+   *
+   * @param searchPath The search path (format: /__search?q=query)
+   * @returns ResolvedTrack containing search results as children
+   */
+  private async resolveSearchContent(
+    searchPath: string
+  ): Promise<ResolvedTrack | undefined> {
+    // Extract query from search path
+    const queryMatch = searchPath.match(/[?&]q=([^&]*)/)
+    if (!queryMatch) {
+      console.warn('Invalid search path, missing query parameter:', searchPath)
+      return undefined
+    }
+    const query = decodeURIComponent(queryMatch[1] ?? '')
+
+    // Find __search__ route entry
+    const searchRoute = this._configuration.routes?.find(
+      (r) => r.path === '__search__'
+    )
+    if (!searchRoute) {
+      console.warn('No __search__ route configured')
+      return undefined
+    }
+
+    let searchResults: Track[] = []
+
+    // Handle callback-based search
+    if (searchRoute.searchCallback) {
+      searchResults = await searchRoute.searchCallback({ query })
+    }
+    // Handle request config-based search
+    else if (searchRoute.searchConfig) {
+      const searchQueryParams: Record<string, string> = { q: query }
+      const requestConfig = this.httpClient.mergeRequestConfig(
+        searchRoute.searchConfig,
+        {
+          query: searchQueryParams
+        }
+      )
+
+      try {
+        const response = await this.httpClient.executeRequest(requestConfig)
+        searchResults = Array.isArray(response) ? (response as Track[]) : []
+      } catch (error) {
+        console.error('Search failed:', error)
+        return undefined
+      }
+    }
+
+    // Create ResolvedTrack with raw children
+    // Search callbacks should return fresh tracks without contextual URLs (like Android)
+    return {
+      url: searchPath,
+      title: `Search: ${query}`,
+      children: searchResults
+    }
+  }
+
+  /**
+   * Transforms artwork URLs for content and its children.
+   * Supports both static config and resolve/transform callbacks.
+   * Matches Android's artwork URL transformation with full Track access.
+   */
+  private async transformArtworkForContent(
+    content: ResolvedTrack
+  ): Promise<ResolvedTrack> {
+    const artworkConfig = this._configuration.artwork
+    if (!artworkConfig) {
+      return content
+    }
+
+    // Transform parent artwork
+    const parentArtworkSource =
+      await RequestConfigBuilder.resolveArtworkSourceAsync(
+        content,
+        artworkConfig
+      )
+
+    // Transform children artwork
+    let transformedChildren: Track[] | undefined
+    if (content.children) {
+      transformedChildren = await Promise.all(
+        content.children.map(async (track) => {
+          const artworkSource =
+            await RequestConfigBuilder.resolveArtworkSourceAsync(
+              track,
+              artworkConfig
+            )
+          if (artworkSource && !track.artworkSource) {
+            return { ...track, artworkSource }
+          }
+          return track
+        })
+      )
+    }
+
+    return {
+      ...content,
+      artworkSource: parentArtworkSource ?? content.artworkSource,
+      children: transformedChildren ?? content.children
+    }
+  }
+
+  /**
+   * Resolves content from a route using browseCallback, browseStatic, or browseConfig.
+   * Single source of truth for route resolution logic.
+   *
+   * @param route The route configuration to resolve
+   * @param path The path being navigated to
+   * @param routeParams Extracted route parameters
+   * @param errorContext Context string for error logging
+   * @returns ResolvedTrack or undefined if resolution fails
+   */
+  private async resolveRouteContent(
+    route: {
+      browseCallback?: NativeBrowserConfiguration['routes'] extends
+        | (infer R)[]
+        | undefined
+        ? R extends { browseCallback?: infer C }
+          ? C
+          : never
+        : never
+      browseStatic?: ResolvedTrack
+      browseConfig?: NativeBrowserConfiguration['routes'] extends
+        | (infer R)[]
+        | undefined
+        ? R extends { browseConfig?: infer C }
+          ? C
+          : never
+        : never
+    },
+    path: string,
+    routeParams: Record<string, string>,
+    errorContext: string
+  ): Promise<ResolvedTrack | undefined> {
+    // Handle callback-based route
+    if (route.browseCallback) {
+      const result = await route.browseCallback({ path, routeParams })
+      if ('error' in result) {
+        console.error(`${errorContext} browse error:`, result.error)
+        this.navigationErrorManager.setNavigationError(
+          'callback-error',
+          result.error,
+          path
+        )
+        return undefined
+      }
+      return result
+    }
+
+    // Handle static ResolvedTrack route
+    if (route.browseStatic) {
+      return route.browseStatic
+    }
+
+    // Handle request config-based route
+    if (route.browseConfig) {
+      const requestConfig = this.httpClient.mergeRequestConfig(
+        route.browseConfig,
+        { path }
+      )
+      try {
+        const response = await this.httpClient.executeRequest(requestConfig)
+        return response as ResolvedTrack
+      } catch (error: unknown) {
+        console.error(`Failed to resolve ${errorContext}:`, error)
+        this.handleNavigationError(error, path)
+        return undefined
+      }
+    }
+
+    return undefined
+  }
+
+  /**
+   * Resolves content for a specific path using configured routes.
+   */
+  private async resolveContent(
+    path: string
+  ): Promise<ResolvedTrack | undefined> {
+    const routes = this._configuration.routes
+    if (!routes || routes.length === 0) {
+      return undefined
+    }
+
+    // Convert routes array to record for SimpleRouter
+    const routePatterns: Record<
+      string,
+      {
+        browseCallback?: (typeof routes)[0]['browseCallback']
+        browseConfig?: (typeof routes)[0]['browseConfig']
+        browseStatic?: (typeof routes)[0]['browseStatic']
+      }
+    > = {}
+
+    for (const route of routes) {
+      // Skip special routes
+      if (route.path.startsWith('__')) continue
+
+      routePatterns[route.path] = {
+        browseCallback: route.browseCallback,
+        browseConfig: route.browseConfig,
+        browseStatic: route.browseStatic
+      }
+    }
+
+    // Try to match route
+    const match = this.router.findBestMatch(path, routePatterns)
+    if (match) {
+      const [matchedPattern, routeMatch] = match
+      const matchedRoute = routes.find((r) => r.path === matchedPattern)
+      if (matchedRoute) {
+        return this.resolveRouteContent(
+          matchedRoute,
+          path,
+          routeMatch.params,
+          'Route'
+        )
+      }
+    }
+
+    // Fall back to __default__ route
+    const defaultRoute = routes.find((r) => r.path === '__default__')
+    if (defaultRoute) {
+      return this.resolveRouteContent(defaultRoute, path, {}, 'Default route')
+    }
+
+    return undefined
+  }
+
+  /**
+   * Queries tabs from the __tabs__ route.
+   */
+  private async queryTabs(): Promise<Track[]> {
+    const tabsRoute = this._configuration.routes?.find(
+      (r) => r.path === '__tabs__'
+    )
+    if (!tabsRoute) {
+      return []
+    }
+
+    const result = await this.resolveRouteContent(tabsRoute, '/', {}, 'Tabs')
+    const tabs = result?.children ?? []
+
+    // Transform artwork URLs on tabs
+    return RequestConfigBuilder.transformTracksArtwork(
+      tabs,
+      this._configuration.artwork
+    )
+  }
+
+  /**
+   * Checks if the configuration has valid routes.
+   */
+  private hasValidConfiguration(): boolean {
+    return (
+      this._configuration.routes !== undefined &&
+      this._configuration.routes.length > 0
+    )
+  }
+
+  /**
+   * Expands a queue from a contextual URL.
+   * Resolves the parent container to get all siblings.
+   * Matches Android's BrowserManager.expandQueueFromContextualUrl() behavior.
+   *
+   * @param contextualUrl The contextual URL (format: /path?__trackId=trackSrc)
+   * @returns Object with tracks and selectedIndex, or undefined if expansion fails
+   */
+  async expandQueueFromContextualUrl(
+    contextualUrl: string
+  ): Promise<{ tracks: Track[]; selectedIndex: number } | undefined> {
+    const trackId = BrowserPathHelper.extractTrackId(contextualUrl)
+    if (!trackId) return undefined
+
+    try {
+      // Resolve the parent container to get all siblings
+      const parentPath = BrowserPathHelper.stripTrackId(contextualUrl)
+      const parentResolvedTrack = await this.resolveContent(parentPath)
+      const children = parentResolvedTrack?.children
+
+      if (!children || children.length === 0) {
+        console.warn('Parent has no children, cannot expand queue')
+        return undefined
+      }
+
+      // Filter to only playable tracks (tracks with src)
+      const playableTracks = children.filter((track) => track.src != null)
+
+      if (playableTracks.length === 0) {
+        console.warn('Parent has no playable tracks, cannot expand queue')
+        return undefined
+      }
+
+      // Find the index of the selected track in the playable tracks array
+      const selectedIndex = playableTracks.findIndex(
+        (track) => track.src === trackId
+      )
+
+      if (selectedIndex < 0) {
+        console.warn(
+          `Track with src='${trackId}' not found in playable children`
+        )
+        return undefined
+      }
+
+      // Check singleTrack setting - if true, return only the selected track
+      if (this._configuration.singleTrack) {
+        return {
+          tracks: [assertedNotNullish(playableTracks[selectedIndex])],
+          selectedIndex: 0
+        }
+      }
+      return { tracks: playableTracks, selectedIndex }
+    } catch (error) {
+      console.error(
+        `Error expanding queue from contextual URL: ${contextualUrl}`,
+        error
+      )
+      return undefined
+    }
+  }
+
+  /**
+   * Resolves media items for playback with queue expansion support.
+   * Handles search results, contextual URLs, and fallback to single track.
+   * Matches Android's BrowserManager.resolveMediaItemsForPlayback() behavior.
+   *
+   * @param tracks The tracks to resolve
+   * @param startIndex The starting index
+   * @param startPositionMs The starting position in milliseconds
+   * @param searchQuery Optional search query that generated these tracks
+   * @returns Object with expanded tracks and starting index
+   */
+  async resolveMediaItemsForPlayback(
+    tracks: Track[],
+    startIndex: number,
+    startPositionMs: number,
+    searchQuery?: string
+  ): Promise<{ tracks: Track[]; startIndex: number; startPositionMs: number }> {
+    // Single track: check for search context or contextual URL
+    if (tracks.length === 1) {
+      const track = assertedNotNullish(tracks[0])
+      const trackUrl = track.url
+
+      // If search query present, expand search results
+      if (searchQuery) {
+        // Execute search (will hit cache if already performed)
+        const searchResults = await this.resolveSearchContent(
+          BrowserPathHelper.createSearchPath(searchQuery)
+        )
+        const searchTracks = searchResults?.children
+
+        if (searchTracks && searchTracks.length > 0) {
+          // Find the selected track in search results
+          const selectedIdx = searchTracks.findIndex(
+            (t) => t.url === trackUrl || t.src === track.src
+          )
+
+          if (selectedIdx >= 0) {
+            return {
+              tracks: searchTracks,
+              startIndex: selectedIdx,
+              startPositionMs
+            }
+          }
+        }
+      }
+
+      // Check if contextual URL - expand from parent
+      // Note: The queueSourcePath optimization is handled by the caller (NativeAudioBrowser.navigateTrackAsync)
+      // which has access to the existing queue and can skip to the track directly.
+      // This matches Android where MediaSessionCallback handles the optimization before calling
+      // BrowserManager.resolveMediaItemsForPlayback.
+      if (trackUrl && BrowserPathHelper.isContextual(trackUrl)) {
+        const parentPath = BrowserPathHelper.stripTrackId(trackUrl)
+        const expanded = await this.expandQueueFromContextualUrl(trackUrl)
+
+        if (expanded) {
+          // Store source path for optimization by caller on next invocation
+          this._queueSourcePath = parentPath
+          return {
+            tracks: expanded.tracks,
+            startIndex: expanded.selectedIndex,
+            startPositionMs
+          }
+        }
+      }
+    }
+
+    // No expansion - use tracks as-is
+    return { tracks, startIndex, startPositionMs }
+  }
+
+  /**
+   * Gets the default navigation path (first tab URL or '/').
+   */
+  private getDefaultPath(): string {
+    // Try to get first tab as default path
+    if (this._tabs && this._tabs.length > 0) {
+      const firstTab = this._tabs[0]
+      return firstTab?.url ?? '/'
+    }
+    return '/'
+  }
+}