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

package/src/features/playback/trackPlaybackTime.ts

@@ -1,101 +0,0 @@
-import type { Track } from '../../types/browser-nodes'
-import { nativeBrowser } from '../../native'
-import { onActiveTrackChanged } from '../queue/activeTrack'
-
-// MARK: - Types
-
-export interface PlaybackElapsed {
-  /** Cumulative seconds spent `playing` since this subscription started. */
-  total: number
-  /** Seconds played since the previous callback (≈ `period`). */
-  sinceLast: number
-  /** The currently playing track (id / src / url / title …), if any. */
-  track?: Track
-}
-
-interface Handle {
-  period: number
-  totalSeconds: number
-  lastFireSeconds: number
-  callback: (elapsed: PlaybackElapsed) => void
-}
-
-// MARK: - State
-
-const handles = new Set<Handle>()
-let installed = false
-let currentTrack: Track | undefined
-
-// The native tick fires once per second while playback is `playing` (and stops
-// while paused/buffering/stopped), so advancing each handle by one second per
-// tick yields cumulative *playback* time that freezes on interruption.
-function onTick() {
-  for (const handle of handles) {
-    handle.totalSeconds += 1
-    const sinceLast = handle.totalSeconds - handle.lastFireSeconds
-    if (sinceLast >= handle.period) {
-      handle.lastFireSeconds = handle.totalSeconds
-      handle.callback({
-        total: handle.totalSeconds,
-        sinceLast,
-        track: currentTrack
-      })
-    }
-  }
-}
-
-function install() {
-  if (installed) return
-  installed = true
-  nativeBrowser.onPlaybackInterval = onTick
-  onActiveTrackChanged.addListener((event) => {
-    currentTrack = event.track
-  })
-}
-
-// MARK: - Public API
-
-/**
- * Calls `callback` every `period` seconds of cumulative playback — time spent in
- * the `playing` state. The clock advances only while playing and freezes on
- * pause/buffering/stop, resuming where it left off; it is never reset (cancel and
- * re-subscribe for a fresh `total`). Coarse, best-effort cadence (~1s resolution),
- * not a precise timer.
- *
- * Typical use is a periodic "still listening" signal: fire an analytics ping, a
- * listen-check, or a heartbeat every N seconds of *actual* listening, so paused
- * time doesn't inflate the count.
- *
- * Note this counts cumulative play time across the whole session, NOT per track:
- * `total` keeps climbing through track changes, and `track` only tells you what
- * was playing at the moment each callback fired. To measure playtime per track,
- * subscribe to {@link onActiveTrackChanged} and cancel + re-subscribe here on each
- * change, so every track gets a fresh `total` starting at zero.
- *
- * @param callback Invoked once per elapsed `period`, with cumulative play time
- *                 and the currently playing track.
- * @param period  Seconds of playback between calls. Must be >= 1.
- * @returns A function that cancels this subscription (idempotent — safe to call
- *          more than once).
- */
-export function trackPlaybackTime(
-  callback: (elapsed: PlaybackElapsed) => void,
-  period: number
-): () => void {
-  if (!(period >= 1)) {
-    throw new Error('trackPlaybackTime: period must be >= 1')
-  }
-  install()
-  const handle: Handle = {
-    period,
-    totalSeconds: 0,
-    lastFireSeconds: 0,
-    callback
-  }
-  handles.add(handle)
-  if (handles.size === 1) nativeBrowser.setPlaybackIntervalEnabled(true)
-  return () => {
-    if (!handles.delete(handle)) return
-    if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false)
-  }
-}

package/src/features/player/options.test.ts

@@ -1,38 +0,0 @@
-import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
-import { nativeBrowser } from '../../native'
-import { updateOptions } from './options'
-
-vi.mock('../../native', () => ({
-  nativeBrowser: { updateOptions: vi.fn() }
-}))
-
-describe('updateOptions', () => {
-  beforeEach(() => vi.clearAllMocks())
-  afterEach(() => vi.restoreAllMocks())
-
-  it('forwards a nested ios bag to the native layer unchanged', () => {
-    updateOptions({ ios: { carPlayNowPlayingButtons: ['favorite'] } })
-    expect(nativeBrowser.updateOptions).toHaveBeenCalledWith({
-      ios: { carPlayNowPlayingButtons: ['favorite'] }
-    })
-  })
-
-  it('warns on more than 5 CarPlay now-playing buttons', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    updateOptions({
-      ios: {
-        carPlayNowPlayingButtons: [
-          'shuffle',
-          'repeat',
-          'favorite',
-          'playback-rate',
-          'shuffle',
-          'repeat'
-        ]
-      }
-    })
-    expect(warn.mock.calls.some(([m]) => String(m).includes('at most 5'))).toBe(
-      true
-    )
-  })
-})

package/src/features/player/setup.test.ts

@@ -1,125 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-vi.mock('../../native', () => ({
-  nativeBrowser: {
-    setupPlayer: vi.fn().mockResolvedValue(undefined)
-  }
-}))
-
-import { nativeBrowser } from '../../native'
-import { setupPlayer } from './setup'
-
-const native = vi.mocked(nativeBrowser)
-
-beforeEach(() => {
-  vi.clearAllMocks()
-  native.setupPlayer.mockResolvedValue(undefined)
-})
-
-function payload() {
-  expect(native.setupPlayer).toHaveBeenCalledTimes(1)
-  return native.setupPlayer.mock.calls[0]![0]
-}
-
-describe('setupPlayer wire regrouping', () => {
-  it('sends the full launch description in a single native call', async () => {
-    await setupPlayer({
-      retry: true,
-      playWhenReady: true,
-      repeatMode: 'queue',
-      capabilities: { favorite: true }
-    })
-
-    expect(payload()).toEqual({
-      retry: true,
-      playWhenReady: true,
-      repeatMode: 'queue',
-      autoUpdateNowPlayingMetadata: true,
-      nowPlayingMetadataFormatter: undefined,
-      options: { capabilities: { favorite: true } }
-    })
-  })
-
-  it('omits the options bag when no runtime options are given', async () => {
-    await setupPlayer({ retry: true })
-
-    expect(payload()).not.toHaveProperty('options')
-  })
-
-  it('splits the merged android bag into construction and runtime fields', async () => {
-    await setupPlayer({
-      android: {
-        minBuffer: 50_000,
-        wakeMode: 'network',
-        skipSilence: true,
-        remoteButtonLayout: {
-          back: 'jump-backward',
-          forward: 'jump-forward',
-          overflow: ['favorite']
-        }
-      }
-    })
-
-    const sent = payload()
-    expect(sent.android).toEqual({ minBuffer: 50_000, wakeMode: 'network' })
-    expect(sent.options).toEqual({
-      android: {
-        skipSilence: true,
-        remoteButtonLayout: {
-          back: 'jump-backward',
-          forward: 'jump-forward',
-          overflow: ['favorite']
-        }
-      }
-    })
-  })
-
-  it('moves ios playbackRates into the runtime options', async () => {
-    await setupPlayer({
-      ios: { category: 'playback', playbackRates: [0.5, 1, 2] }
-    })
-
-    const sent = payload()
-    expect(sent.ios).toEqual({ category: 'playback' })
-    expect(sent.options).toEqual({ ios: { playbackRates: [0.5, 1, 2] } })
-  })
-
-  it('omits a platform bag that only carried runtime fields', async () => {
-    await setupPlayer({ android: { skipSilence: true } })
-
-    expect(payload()).not.toHaveProperty('android')
-  })
-
-  it('forwards meaningful nulls (progress disabled, empty button layout)', async () => {
-    await setupPlayer({
-      progressUpdateEventInterval: null,
-      android: { remoteButtonLayout: null }
-    })
-
-    expect(payload().options).toEqual({
-      progressUpdateEventInterval: null,
-      android: { remoteButtonLayout: null }
-    })
-  })
-
-  it('normalizes a formatter callback and coalesces its undefined to {}', async () => {
-    const formatter = vi.fn(() => undefined)
-    await setupPlayer({ nowPlaying: formatter })
-
-    const sent = payload()
-    expect(sent.autoUpdateNowPlayingMetadata).toBe(true)
-    // The wrapper never lets `undefined` cross the Nitro boundary.
-    expect(
-      sent.nowPlayingMetadataFormatter!({
-        track: { title: 'Station' },
-        playWhenReady: true
-      })
-    ).toEqual({})
-  })
-
-  it('maps nowPlaying: false to disabled metadata publishing', async () => {
-    await setupPlayer({ nowPlaying: false })
-
-    expect(payload().autoUpdateNowPlayingMetadata).toBe(false)
-  })
-})

package/src/features/player/validateOptions.ts

@@ -1,22 +0,0 @@
-import type { IOSUpdateOptions } from './options'
-
-const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
-
-/**
- * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
- * Shared by `updateOptions` and `setupPlayer` (both can carry `ios` options).
- *
- * Lives outside `options.ts` because `features/player/index.ts` re-exports that
- * module wholesale: anything exported there joins the package's runtime surface,
- * `@internal` or not. This file is imported directly by the two callers and by
- * nothing in the barrel.
- */
-export function validateIOSUpdateOptions(ios?: IOSUpdateOptions): void {
-  const buttons = ios?.carPlayNowPlayingButtons
-  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
-    console.warn(
-      `[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` +
-        `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`
-    )
-  }
-}

package/src/features/queue/queue.test.ts

@@ -1,36 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-
-const calls: any[] = []
-vi.mock('../../native', () => ({
-  nativeBrowser: {
-    setQueue: (...a: any[]) => calls.push(['setQueue', ...a]),
-    play: () => calls.push(['play'])
-  }
-}))
-
-import { setQueue } from './queue'
-
-describe('setQueue wrapper', () => {
-  beforeEach(() => {
-    calls.length = 0
-  })
-
-  it('threads startIndex and startPosition to native', () => {
-    const tracks = [{ src: 'a' }, { src: 'b' }] as any
-    setQueue(tracks, 1, 5)
-    expect(calls).toContainEqual(['setQueue', tracks, 1, 5])
-  })
-
-  it('forwards startIndex even when startPosition is omitted', () => {
-    const tracks = [{ src: 'a' }, { src: 'b' }] as any
-    setQueue(tracks, 1)
-    expect(calls[0]).toEqual(['setQueue', tracks, 1, undefined])
-  })
-
-  it('only sets the queue and does not start playback', () => {
-    setQueue([{ src: 'a' }] as any, 0)
-    // setQueue no longer auto-plays — it preserves the current play/pause
-    // state; callers start playback explicitly with play().
-    expect(calls.map((c) => c[0])).toEqual(['setQueue'])
-  })
-})

package/src/public-surface.test.ts

@@ -1,123 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
-import { describe, it, expect } from 'vitest'
-
-/**
- * Guard on what `import { … } from 'react-native-audio-browser'` can reach.
- *
- * The package root is a chain of unfiltered `export *` barrels, so every
- * `export` in every feature file joins the public surface by default — there is
- * no gate to forget to pass, only one to forget to add.
- *
- * `@internal` alone does not keep a symbol private. It is honoured by
- * `stripInternal` when generating `lib/typescript`, which is what a consumer's
- * TypeScript sees — but React Native resolves `"react-native": "src/index"`, so
- * Metro bundles the *source*, where nothing was stripped. An `@internal` value
- * is therefore invisible to the type checker and fully reachable at runtime:
- * `require('react-native-audio-browser').nativeBrowser` used to hand out the raw
- * Nitro object, whose `on*` properties are the single callback slots the library's
- * emitters own — assigning one unsubscribes every hook in the package.
- *
- * So: values marked `@internal` must not be reachable from the barrel at all.
- * Move them to a module the barrel doesn't re-export (see
- * `features/player/validateOptions.ts`) and import them directly. Types are
- * exempt — they carry no runtime representation, and `stripInternal` genuinely
- * removes them from the published `.d.ts`.
- */
-const SRC = join(process.cwd(), 'src')
-const ENTRY = join(SRC, 'index.ts')
-
-const VALUE_KINDS = new Set([
-  'const',
-  'let',
-  'var',
-  'function',
-  'class',
-  'enum'
-])
-
-function resolveModule(fromFile: string, spec: string): string | undefined {
-  const base = resolve(dirname(fromFile), spec.replace(/\.tsx?$/, ''))
-  return [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')].find(existsSync)
-}
-
-interface Export {
-  name: string
-  file: string
-  internal: boolean
-}
-
-/** Walks the `export *` graph from `entry`, collecting every reachable value export. */
-function collectValueExports(entry: string): Export[] {
-  const found: Export[] = []
-  const seen = new Set<string>()
-
-  const visit = (file: string) => {
-    if (seen.has(file)) return
-    seen.add(file)
-    const source = readFileSync(file, 'utf8')
-
-    for (const [, spec] of source.matchAll(/^export \* from ['"](.+?)['"]/gm)) {
-      const target = resolveModule(file, spec!)
-      if (target) visit(target)
-    }
-
-    const declaration =
-      /^export (?:declare )?(?:async )?(?:abstract )?(const|let|var|function|class|enum) (\w+)/gm
-    for (const match of source.matchAll(declaration)) {
-      if (!VALUE_KINDS.has(match[1]!)) continue
-      // The JSDoc block, if any, is whatever sits directly above the export.
-      const preceding = source.slice(0, match.index)
-      const doc = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/.exec(preceding)?.[0] ?? ''
-      found.push({
-        name: match[2]!,
-        file: relative(SRC, file),
-        internal: /@internal\b/.test(doc)
-      })
-    }
-  }
-
-  visit(entry)
-  return found
-}
-
-describe('public surface', () => {
-  const exports = collectValueExports(ENTRY)
-
-  it('reaches the feature modules at all (the walker still works)', () => {
-    // Cheap canary: if the barrel structure changes shape and the walker stops
-    // resolving, every other assertion here would pass vacuously.
-    expect(exports.map((e) => e.name)).toContain('trackPlaybackTime')
-    expect(exports.length).toBeGreaterThan(100)
-  })
-
-  it('exposes no value marked @internal', () => {
-    const leaked = exports
-      .filter((e) => e.internal)
-      .map((e) => `${e.name}  (${e.file})`)
-    expect(
-      leaked,
-      'These values are tagged @internal but are reachable from the package root ' +
-        'at runtime — stripInternal only hides them from the published types, and ' +
-        'Metro bundles src/. Move each to a module the barrels do not re-export ' +
-        'and import it directly:\n' +
-        leaked.join('\n')
-    ).toEqual([])
-  })
-
-  it('exposes no __-prefixed test hook', () => {
-    const hooks = exports
-      .filter((e) => e.name.startsWith('__'))
-      .map((e) => `${e.name}  (${e.file})`)
-    expect(
-      hooks,
-      'Test-only exports ship to consumers. Drive the unit under test through ' +
-        'the seam it already has (a mocked native slot, say) instead:\n' +
-        hooks.join('\n')
-    ).toEqual([])
-  })
-
-  it('does not re-export the raw Nitro object', () => {
-    expect(exports.map((e) => e.name)).not.toContain('nativeBrowser')
-  })
-})

package/src/utils/artwork.ts

@@ -1,30 +0,0 @@
-import type { ArtworkVariants, TrackArtwork } from '../types/browser-nodes'
-
-/**
- * Whether a track's artwork ships one image per appearance.
- *
- * Narrows the union in one place, so nothing else has to know how it is
- * discriminated.
- */
-export function isArtworkVariants(
-  artwork: TrackArtwork | undefined
-): artwork is ArtworkVariants {
-  return typeof artwork === 'object' && artwork !== null
-}
-
-/**
- * The single artwork URL to use.
- *
- * Mirrors the Swift `Variant_String_ArtworkVariants.url` accessor: a pair
- * resolves to its dark URL unless a scheme is given, because dark is what a
- * single-URL track would have shipped and is the only appearance Android Auto
- * has. Callers that can render per appearance (CarPlay, via a `UIImageAsset`)
- * take the pair itself rather than going through this.
- */
-export function artworkUrl(
-  artwork: TrackArtwork | undefined,
-  scheme: 'light' | 'dark' = 'dark'
-): string | undefined {
-  if (artwork === undefined) return undefined
-  return isArtworkVariants(artwork) ? artwork[scheme] : artwork
-}