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

package/ios/Browser/BrowserPathHelper.swift

@@ -0,0 +1,156 @@
+import Foundation
+
+/// Utility for handling browser paths and contextual URLs in the media browser system.
+///
+/// Handles two types of special paths:
+/// 1. System paths (prefixed with `/__`): Root, recent, and search paths
+/// 2. Contextual URLs: Embed parent context in track identifiers for playback integration
+///
+/// Contextual URL format: `{parentPath}?__trackId={trackSrc}`
+/// Example: "/library/radio?__trackId=song.mp3"
+///
+/// This allows:
+/// - Playable-only tracks (tracks with `src` but no `url`) to be referenced
+/// - Cache lookup to work consistently
+/// - Parent context to be preserved for queue restoration
+enum BrowserPathHelper {
+  /// Root path for media browsing
+  static let rootPath = "/__root"
+
+  /// Recent media path for playback resumption
+  static let recentPath = "/__recent"
+
+  /// Search path prefix (full path is /__search?q=query)
+  static let searchPathPrefix = "/__search"
+
+  /// Offline error placeholder media ID
+  static let offlinePath = "/__offline"
+
+  /// Query parameter name for contextual track identifiers
+  private static let contextualTrackParam = "__trackId"
+
+  /// Check if a path is a special system path (not a regular navigation path)
+  static func isSpecialPath(_ path: String) -> Bool {
+    path == rootPath ||
+      path == recentPath ||
+      path.hasPrefix("\(searchPathPrefix)?")
+  }
+
+  /// Create a search path for a given query
+  static func createSearchPath(_ query: String) -> String {
+    let encodedQuery =
+      query.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? query
+    return "\(searchPathPrefix)?q=\(encodedQuery)"
+  }
+
+  /// Checks if a path contains a contextual track identifier.
+  ///
+  /// - Parameter path: The URL path to check
+  /// - Returns: true if the path contains the contextual track parameter
+  static func isContextual(_ path: String) -> Bool {
+    path.contains("?\(contextualTrackParam)=")
+      || path.contains("&\(contextualTrackParam)=")
+  }
+
+  /// Strips the __trackId parameter from a contextual URL to get the parent path.
+  /// If the URL is not contextual, returns it unchanged.
+  ///
+  /// - Parameter url: The URL to process
+  /// - Returns: The URL without the __trackId parameter
+  ///
+  /// Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+  /// Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
+  static func stripTrackId(_ url: String) -> String {
+    guard isContextual(url) else {
+      return url
+    }
+
+    guard var components = URLComponents(string: url) else {
+      return url
+    }
+
+    // Filter out __trackId parameter
+    components.queryItems = components.queryItems?.filter { $0.name != contextualTrackParam }
+
+    // If no query items left, clear the query string entirely
+    if components.queryItems?.isEmpty == true {
+      components.queryItems = nil
+    }
+
+    return components.string ?? url
+  }
+
+  /// Builds a contextual URL by appending a track identifier to a parent path.
+  /// Handles existing query parameters correctly.
+  ///
+  /// - Parameters:
+  ///   - parentPath: The parent container path
+  ///   - trackId: The track identifier (typically the `src` value)
+  /// - Returns: A contextual URL combining parent path and track ID
+  ///
+  /// Example: build("/library", "song.mp3") → "/library?__trackId=song.mp3"
+  /// Example: build("/search?q=jazz", "song.mp3") → "/search?q=jazz&__trackId=song.mp3"
+  static func build(parentPath: String, trackId: String) -> String {
+    let encodedTrackId =
+      trackId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? trackId
+    let separator = parentPath.contains("?") ? "&" : "?"
+    return "\(parentPath)\(separator)\(contextualTrackParam)=\(encodedTrackId)"
+  }
+
+  /// Extracts the track ID from a contextual URL.
+  /// Returns nil if the URL is not contextual or doesn't contain the track ID parameter.
+  ///
+  /// - Parameter path: The contextual URL to parse
+  /// - Returns: The extracted track ID, or nil if not found
+  ///
+  /// Example: "/library/radio?__trackId=song.mp3" → "song.mp3"
+  static func extractTrackId(_ path: String) -> String? {
+    guard isContextual(path) else {
+      return nil
+    }
+
+    guard let components = URLComponents(string: path) else {
+      return nil
+    }
+
+    return components.queryItems?.first { $0.name == contextualTrackParam }?.value
+  }
+
+  /// Combines a base URL with a path, ensuring proper slash handling.
+  ///
+  /// - Parameters:
+  ///   - baseUrl: The base URL (can be nil)
+  ///   - path: The path to append
+  /// - Returns: The combined URL with proper slash handling
+  ///
+  /// Examples:
+  /// - buildUrl("http://example.com", "api/test") → "http://example.com/api/test"
+  /// - buildUrl("http://example.com/", "/api/test") → "http://example.com/api/test"
+  /// - buildUrl(nil, "/api/test") → "/api/test"
+  /// - buildUrl(nil, "http://full.url") → "http://full.url"
+  static func buildUrl(baseUrl: String?, path: String) -> String {
+    // If path is already a full URL, return it as-is
+    if path.hasPrefix("http://") || path.hasPrefix("https://") {
+      return path
+    }
+
+    // If no baseUrl, return path as-is
+    guard let baseUrl else {
+      return path
+    }
+
+    // Ensure baseUrl ends with / and path doesn't start with /
+    var normalizedBase = baseUrl
+    while normalizedBase.hasSuffix("/") {
+      normalizedBase.removeLast()
+    }
+    normalizedBase += "/"
+
+    var normalizedPath = path
+    while normalizedPath.hasPrefix("/") {
+      normalizedPath.removeFirst()
+    }
+
+    return "\(normalizedBase)\(normalizedPath)"
+  }
+}

package/ios/Browser/JsonModels.swift

@@ -0,0 +1,165 @@
+import Foundation
+import NitroModules
+
+/// JSON serializable models for parsing API responses.
+/// These will be converted to Nitro types after parsing.
+
+/// JSON model for resolved track (container with children).
+struct JsonResolvedTrack: Codable {
+  let url: String
+  let title: String
+  let subtitle: String?
+  let artwork: String?
+  let artist: String?
+  let album: String?
+  let description: String?
+  let genre: String?
+  let duration: Double?
+  let children: [JsonTrack]?
+  let src: String?
+  let style: String?
+  let childrenStyle: String?
+  let groupTitle: String?
+  let live: Bool?
+
+  init(
+    url: String,
+    title: String,
+    subtitle: String? = nil,
+    artwork: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    description: String? = nil,
+    genre: String? = nil,
+    duration: Double? = nil,
+    children: [JsonTrack]? = nil,
+    src: String? = nil,
+    style: String? = nil,
+    childrenStyle: String? = nil,
+    groupTitle: String? = nil,
+    live: Bool? = nil,
+  ) {
+    self.url = url
+    self.title = title
+    self.subtitle = subtitle
+    self.artwork = artwork
+    self.artist = artist
+    self.album = album
+    self.description = description
+    self.genre = genre
+    self.duration = duration
+    self.children = children
+    self.src = src
+    self.style = style
+    self.childrenStyle = childrenStyle
+    self.groupTitle = groupTitle
+    self.live = live
+  }
+}
+
+/// JSON model for individual tracks.
+struct JsonTrack: Codable {
+  let url: String?
+  let title: String
+  let subtitle: String?
+  let artwork: String?
+  let artist: String?
+  let album: String?
+  let description: String?
+  let genre: String?
+  let duration: Double?
+  let src: String?
+  let style: String?
+  let childrenStyle: String?
+  let groupTitle: String?
+  let live: Bool?
+
+  init(
+    url: String? = nil,
+    title: String,
+    subtitle: String? = nil,
+    artwork: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    description: String? = nil,
+    genre: String? = nil,
+    duration: Double? = nil,
+    src: String? = nil,
+    style: String? = nil,
+    childrenStyle: String? = nil,
+    groupTitle: String? = nil,
+    live: Bool? = nil,
+  ) {
+    self.url = url
+    self.title = title
+    self.subtitle = subtitle
+    self.artwork = artwork
+    self.artist = artist
+    self.album = album
+    self.description = description
+    self.genre = genre
+    self.duration = duration
+    self.src = src
+    self.style = style
+    self.childrenStyle = childrenStyle
+    self.groupTitle = groupTitle
+    self.live = live
+  }
+}
+
+// MARK: - Convert JSON models to Nitro types
+
+private extension String {
+  func toTrackStyle() -> TrackStyle? {
+    TrackStyle(fromString: lowercased())
+  }
+}
+
+extension JsonResolvedTrack {
+  func toNitro() -> ResolvedTrack {
+    ResolvedTrack(
+      url: url,
+      children: children?.map { $0.toNitro() },
+      src: src,
+      artwork: artwork,
+      artworkSource: nil,
+      artworkCarPlayTinted: nil,
+      title: title,
+      subtitle: subtitle,
+      artist: artist,
+      album: album,
+      description: description,
+      genre: genre,
+      duration: duration,
+      style: style?.toTrackStyle(),
+      childrenStyle: childrenStyle?.toTrackStyle(),
+      favorited: nil,
+      groupTitle: groupTitle,
+      live: live,
+    )
+  }
+}
+
+extension JsonTrack {
+  func toNitro() -> Track {
+    Track(
+      url: url,
+      src: src,
+      artwork: artwork,
+      artworkSource: nil,
+      artworkCarPlayTinted: nil,
+      title: title,
+      subtitle: subtitle,
+      artist: artist,
+      album: album,
+      description: description,
+      genre: genre,
+      duration: duration,
+      style: style?.toTrackStyle(),
+      childrenStyle: childrenStyle?.toTrackStyle(),
+      favorited: nil,
+      groupTitle: groupTitle,
+      live: live,
+    )
+  }
+}

package/ios/Browser/SimpleRouter.swift

@@ -0,0 +1,184 @@
+import Foundation
+
+/// Result of a successful route match.
+struct RouteMatch {
+  /// Extracted parameters from the path (e.g., {id} → "123")
+  /// For tail wildcards, the remaining path is stored in params["tail"]
+  let params: [String: String]
+
+  /// Specificity score (higher = more specific match)
+  let specificity: Int
+
+  init(params: [String: String] = [:], specificity: Int = 0) {
+    self.params = params
+    self.specificity = specificity
+  }
+}
+
+/// Protocol for route entries that can be matched.
+protocol RouteEntry {
+  var path: String { get }
+}
+
+/// Simple route matcher for path patterns with parameter extraction.
+///
+/// Supports patterns like:
+/// - /artists - exact match
+/// - /artists/{id} - parameter extraction
+/// - /artists/{id}/albums - multiple segments with parameters
+/// - /artists/* - wildcard match (matches any single segment)
+/// - /files/** - tail wildcard (matches remaining path segments)
+///
+/// Route specificity rules:
+/// - More path segments = higher specificity
+/// - Constant segments > parameter segments > wildcards > tail wildcards
+/// - Most specific route wins
+final class SimpleRouter {
+  /// Finds the best matching route for the given path.
+  ///
+  /// - Parameters:
+  ///   - path: The incoming path to match (e.g., "/artists/123")
+  ///   - routes: Array of route entries to match against
+  /// - Returns: Tuple of (route, match result) or nil if no match
+  func findBestMatch<T: RouteEntry>(path: String, routes: [T]) -> (route: T, match: RouteMatch)? {
+    var bestMatch: (route: T, match: RouteMatch)?
+
+    for route in routes {
+      if let match = matchPattern(pattern: route.path, path: path) {
+        if bestMatch == nil || match.specificity > bestMatch!.match.specificity {
+          bestMatch = (route, match)
+        }
+      }
+    }
+
+    return bestMatch
+  }
+
+  /// Attempts to match a single pattern against a path.
+  ///
+  /// - Parameters:
+  ///   - pattern: Route pattern (e.g., "/artists/{id}", "/files/*", "/api/**")
+  ///   - path: Incoming path (e.g., "/artists/123")
+  /// - Returns: RouteMatch if successful, nil otherwise
+  private func matchPattern(pattern: String, path: String) -> RouteMatch? {
+    let patternSegments = pattern.split(separator: "/").map(String.init)
+    let pathSegments = path.split(separator: "/").map(String.init)
+
+    var params: [String: String] = [:]
+    var constantSegments = 0
+    var parameterSegments = 0
+    var wildcardSegments = 0
+    var hasTailWildcard = false
+
+    // Check for tail wildcard at end
+    if let lastSegment = patternSegments.last, lastSegment == "**" {
+      hasTailWildcard = true
+
+      // For tail wildcard, pattern must have <= path segments
+      if patternSegments.count - 1 > pathSegments.count {
+        return nil
+      }
+
+      // Match all segments except the tail wildcard
+      for i in 0 ..< (patternSegments.count - 1) {
+        guard
+          matchSingleSegment(
+            patternSegment: patternSegments[i],
+            pathSegment: pathSegments[i],
+            params: &params,
+          )
+        else {
+          return nil
+        }
+
+        updateSegmentCounts(
+          patternSegment: patternSegments[i],
+          constantSegments: &constantSegments,
+          parameterSegments: &parameterSegments,
+          wildcardSegments: &wildcardSegments,
+        )
+      }
+
+      // Capture remaining path segments as "tail" parameter (matches Kotlin behavior)
+      if pathSegments.count > patternSegments.count - 1 {
+        let remainingSegments = pathSegments.dropFirst(patternSegments.count - 1)
+        params["tail"] = remainingSegments.joined(separator: "/")
+      }
+    } else {
+      // Normal matching - must have same number of segments
+      if patternSegments.count != pathSegments.count {
+        return nil
+      }
+
+      for i in patternSegments.indices {
+        guard
+          matchSingleSegment(
+            patternSegment: patternSegments[i],
+            pathSegment: pathSegments[i],
+            params: &params,
+          )
+        else {
+          return nil
+        }
+
+        updateSegmentCounts(
+          patternSegment: patternSegments[i],
+          constantSegments: &constantSegments,
+          parameterSegments: &parameterSegments,
+          wildcardSegments: &wildcardSegments,
+        )
+      }
+    }
+
+    // Specificity calculation (higher = more specific):
+    // - Constants: 1000 points each
+    // - Parameters: 100 points each
+    // - Single wildcards: 10 points each
+    // - Tail wildcard: 1 point
+    // - Base path length: segments count
+    let specificity =
+      (constantSegments * 1000)
+        + (parameterSegments * 100)
+        + (wildcardSegments * 10)
+        + (hasTailWildcard ? 1 : 0)
+        + patternSegments.count
+
+    return RouteMatch(params: params, specificity: specificity)
+  }
+
+  private func matchSingleSegment(
+    patternSegment: String,
+    pathSegment: String,
+    params: inout [String: String],
+  ) -> Bool {
+    // Parameter segment: {paramName}
+    if patternSegment.hasPrefix("{"), patternSegment.hasSuffix("}") {
+      let paramName = String(patternSegment.dropFirst().dropLast())
+      params[paramName] = pathSegment
+      return true
+    }
+
+    // Single wildcard: *
+    if patternSegment == "*" {
+      return true
+    }
+
+    // Constant segment: must match exactly
+    return patternSegment == pathSegment
+  }
+
+  private func updateSegmentCounts(
+    patternSegment: String,
+    constantSegments: inout Int,
+    parameterSegments: inout Int,
+    wildcardSegments: inout Int,
+  ) {
+    if patternSegment.hasPrefix("{"), patternSegment.hasSuffix("}") {
+      parameterSegments += 1
+    } else if patternSegment == "*" {
+      wildcardSegments += 1
+    } else {
+      constantSegments += 1
+    }
+  }
+}