react-native-audio-browser 0.2.0-next.8 → 0.2.0

package/src/features/browser-config.ts

@@ -1,293 +0,0 @@
-import type {
-  BrowserConfiguration,
-  BrowserSource,
-  BrowserSourceCallback,
-  RequestConfigResolver,
-  ResolvedTrack,
-  RouteConfig,
-  SearchSource,
-  SearchSourceCallback,
-  TabsSource,
-  Track,
-  TransformableRequestConfig
-} from '../types'
-import type {
-  NativeBrowserConfiguration,
-  NativeRouteEntry
-} from '../types/browser-native'
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Configuration Transformation
-//
-// Lowers the public BrowserConfiguration into the flattened native shape.
-// Deliberately NOT re-exported from features/index.ts — these helpers are
-// internal (and unit-tested directly), not public API.
-// ─────────────────────────────────────────────────────────────────────────────
-
-function isCallback(
-  source: unknown
-): source is (...args: unknown[]) => unknown {
-  return typeof source === 'function'
-}
-
-function isObjectValue(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-function isTransformableRequestConfig(
-  source: unknown
-): source is TransformableRequestConfig {
-  if (!isObjectValue(source)) return false
-  // Any RequestConfig key marks a request config. A static ResolvedTrack
-  // shares none of these at the top level (its per-track request override is
-  // nested under `request`).
-  return (
-    'baseUrl' in source ||
-    'path' in source ||
-    'headers' in source ||
-    'query' in source ||
-    'method' in source ||
-    'body' in source ||
-    'contentType' in source ||
-    'userAgent' in source ||
-    'transform' in source ||
-    'transformSync' in source
-  )
-}
-
-function isRouteConfig(source: unknown): source is RouteConfig {
-  if (!isObjectValue(source)) return false
-  // `browse`/`media` keys only exist on RouteConfig. `artwork` also exists on
-  // a static ResolvedTrack — but there it is a string URL, while RouteConfig's
-  // is a config object, so only an object-valued `artwork` marks a RouteConfig.
-  return (
-    'browse' in source || 'media' in source || isObjectValue(source.artwork)
-  )
-}
-
-function splitLayer(
-  layer: TransformableRequestConfig | RequestConfigResolver | undefined
-): {
-  config?: TransformableRequestConfig
-  resolver?: () => Promise<TransformableRequestConfig>
-} {
-  if (!layer) return {}
-  // A function is a resolver thunk; an object is a static layer config. (The
-  // `request`/`browse` layer fields are object-only today, so this is
-  // unambiguous — unlike route/search sources which already accept a callback.)
-  if (isCallback(layer)) {
-    const resolve = layer as RequestConfigResolver
-    // Normalize the sync-or-async resolver to Promise-only for the bridge so it
-    // never sees a `T | Promise<T>` variant (which misreads the async case).
-    // Resolvers run once per content generation, so the wrap costs nothing.
-    return { resolver: () => Promise.resolve(resolve()) }
-  }
-  return { config: layer as TransformableRequestConfig }
-}
-
-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 — the endpoint returns a page object whose
-  // children are the tabs (same shape as a browse endpoint).
-  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__'
-
-// Exported for hasSearch() in browser.ts, which inspects the lowered config.
-// DEFAULT_ROUTE_PATH and TABS_ROUTE_PATH are not needed outside this module.
-export const SEARCH_ROUTE_PATH = '__search__'
-
-function flattenRoutes(
-  routes: Record<string, BrowserSource | RouteConfig> | undefined,
-  tabs: TabsSource | undefined,
-  search: SearchSource | undefined
-): NativeRouteEntry[] | undefined {
-  const entries: NativeRouteEntry[] = []
-
-  // Add explicit routes. The '*' key is the optional custom default — it maps to
-  // the __default__ entry (used when no other route matches). Without it, an
-  // unmatched browse path is fetched via request + browse config applied to the
-  // path (handled natively), so no __default__ entry is needed.
-  if (routes) {
-    for (const [path, source] of Object.entries(routes)) {
-      entries.push(
-        flattenRouteEntry(path === '*' ? DEFAULT_ROUTE_PATH : path, source)
-      )
-    }
-  }
-
-  // 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
-}
-
-/** Android Auto / CarPlay display at most this many tabs. */
-const MAX_TABS = 4
-
-/**
- * Dev-only sanity checks for a BrowserConfiguration. Warns (never throws) on
- * mistakes the type system cannot catch: reserved route keys, route values
- * that match no source shape (and would be served as garbage static content),
- * and platform display limits. Called by configureBrowser under __DEV__.
- */
-export function validateBrowserConfiguration(
-  config: BrowserConfiguration
-): void {
-  const warn = (message: string) =>
-    console.warn(`[react-native-audio-browser] configureBrowser: ${message}`)
-
-  if (config.routes) {
-    for (const [path, source] of Object.entries(config.routes)) {
-      if (path !== '*' && path.startsWith('__')) {
-        warn(
-          `route "${path}" uses the reserved "__" prefix and will conflict ` +
-            `with internal routing entries. Rename the route.`
-        )
-        continue
-      }
-      if (
-        !isCallback(source) &&
-        !isRouteConfig(source) &&
-        !isTransformableRequestConfig(source)
-      ) {
-        // Falls through to the static-page branch; a page needs url + title.
-        const page = source as Partial<ResolvedTrack>
-        if (typeof page.url !== 'string' || typeof page.title !== 'string') {
-          warn(
-            `route "${path}" matched no source shape — expected a callback, ` +
-              `a request config ({ baseUrl, path, headers, ... }), a ` +
-              `RouteConfig ({ browse, media, artwork }), or a static page ` +
-              `({ url, title, children? }). It will be served as static ` +
-              `content and likely render a blank screen.`
-          )
-        }
-      }
-    }
-  }
-
-  if (Array.isArray(config.tabs) && config.tabs.length > MAX_TABS) {
-    warn(
-      `${config.tabs.length} tabs configured; Android Auto and CarPlay ` +
-        `display at most ${MAX_TABS} — extra tabs will not be shown.`
-    )
-  }
-}
-
-export function toNativeConfig(
-  config: BrowserConfiguration
-): NativeBrowserConfiguration {
-  const request = splitLayer(config.request)
-  const browse = splitLayer(config.browse)
-  return {
-    path: config.path,
-    request: request.config,
-    requestResolver: request.resolver,
-    browse: browse.config,
-    browseResolver: browse.resolver,
-    media: config.media,
-    artwork: config.artwork,
-    nowPlayingArtwork: config.nowPlayingArtwork,
-    routes: flattenRoutes(config.routes, config.tabs, config.search),
-    singleTrack: config.singleTrack,
-    handleTrackLoad: config.handleTrackLoad,
-    androidControllerOfflineError: config.androidControllerOfflineError,
-    carPlayLoadingTitle: config.carPlayLoadingTitle,
-    resolveAlbumUrl: config.resolveAlbumUrl,
-    formatNavigationError: config.formatNavigationError
-  }
-}

package/src/features/browser.test.ts

@@ -1,19 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-vi.mock('../native', () => ({
-  nativeBrowser: { configuration: undefined }
-}))
-
-import { configureBrowser, getBrowserConfiguration } from './browser'
-
-describe('getBrowserConfiguration', () => {
-  it('returns undefined before the browser is configured', () => {
-    expect(getBrowserConfiguration()).toBeUndefined()
-  })
-
-  it('returns the last configuration in its public shape', () => {
-    const config = { tabs: [{ title: 'Home', url: '/' }] }
-    configureBrowser(config)
-    expect(getBrowserConfiguration()).toBe(config)
-  })
-})

package/src/features/carConnection.ts

@@ -1,36 +0,0 @@
-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/gate.test.ts

@@ -1,72 +0,0 @@
-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

@@ -1,155 +0,0 @@
-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 An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
- */
-export const onGate = LazyNativeEmitter.emitterize<GateEvent>(
-  (cb) => (nativeBrowser.onGate = cb)
-)

package/src/features/playback/trackPlaybackTime.test.ts

@@ -1,80 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-
-const nativeMock = {
-  onPlaybackInterval: undefined as undefined | (() => void),
-  setPlaybackIntervalEnabled: vi.fn()
-}
-vi.mock('../../native', () => ({
-  get nativeBrowser() {
-    return nativeMock
-  }
-}))
-vi.mock('../queue/activeTrack', () => ({
-  onActiveTrackChanged: { addListener: vi.fn(() => () => {}) }
-}))
-
-import { trackPlaybackTime } from './trackPlaybackTime'
-
-beforeEach(() => {
-  nativeMock.setPlaybackIntervalEnabled.mockClear()
-})
-
-/**
- * Drives the fan-out through the same slot the native side does: `install()`
- * assigns `onPlaybackInterval`, so calling it here also asserts that wiring
- * exists — a dedicated test-only export would skip it.
- */
-function tick(times = 1) {
-  for (let i = 0; i < times; i++) {
-    if (!nativeMock.onPlaybackInterval) {
-      throw new Error('trackPlaybackTime never installed onPlaybackInterval')
-    }
-    nativeMock.onPlaybackInterval()
-  }
-}
-
-describe('trackPlaybackTime', () => {
-  it('enables native tick on first subscriber, disables on last', () => {
-    const a = trackPlaybackTime(() => {}, 5)
-    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(true)
-    const b = trackPlaybackTime(() => {}, 5)
-    a()
-    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(true) // b still active
-    b()
-    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(
-      false
-    )
-  })
-
-  it('fires every `period` seconds with cumulative total', () => {
-    const calls: { total: number; sinceLast: number }[] = []
-    const cancel = trackPlaybackTime(
-      (e) => calls.push({ total: e.total, sinceLast: e.sinceLast }),
-      3
-    )
-    tick(2)
-    expect(calls).toEqual([])
-    tick(1) // total now 3 → fires
-    expect(calls).toEqual([{ total: 3, sinceLast: 3 }])
-    tick(3) // total now 6 → fires again
-    expect(calls).toEqual([
-      { total: 3, sinceLast: 3 },
-      { total: 6, sinceLast: 3 }
-    ])
-    cancel()
-    tick(3)
-    expect(calls).toHaveLength(2) // cancelled
-  })
-
-  it('runs multiple subscribers at independent periods', () => {
-    const fast: number[] = []
-    const slow: number[] = []
-    const cancelFast = trackPlaybackTime((e) => fast.push(e.total), 1)
-    const cancelSlow = trackPlaybackTime((e) => slow.push(e.total), 2)
-    tick(2)
-    expect(fast).toEqual([1, 2])
-    expect(slow).toEqual([2])
-    cancelFast()
-    cancelSlow()
-  })
-})