Files
otunes/apps/mobile/components/app-intent-bridge.tsx
T
joshuafhigginsandClaude Opus 5.5 Verified 4ef610c143 fix: hide unknown release years on every platform
Unknown years are stored as 0 and dates as "". Album detail now returns a
null year and the Siri catalog sends an empty year instead of "0", so no
client has to special-case 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 15:31:50 -05:00

823 lines
26 KiB
TypeScript

import { useConvex, useQuery } from "convex/react"
import * as AppIntents from "expo-app-intents"
import type { AppIntentEntity, AppIntentInvocation } from "expo-app-intents"
import { useEffect, useMemo, useRef, useSyncExternalStore } from "react"
import { AppState } from "react-native"
import {
completeMusicInvocation,
publishMusicCatalog,
trackMusicCatalogSync,
} from "@/lib/app-intents"
import { useAppNavigation } from "@/lib/app-navigation"
import {
ANONYMOUS_CACHE_SCOPE,
useCacheScope,
} from "@/contexts/persistent-cache"
import { usePlayback } from "@/contexts/playback"
import {
FAVORITES_PLAYLIST_ID,
loadHandledIntentIds,
rememberHandledIntentId,
} from "@/lib/app-intent-handled"
import { showError } from "@/lib/toast"
import { fetchCachedQuery } from "@otunes/convex/client/cached-query"
import { getPlaybackStore } from "@otunes/convex/client/playback-store"
import type { RepeatMode } from "@otunes/convex/client/playback-queue"
import { api } from "@otunes/convex/_generated/api"
import type { Id } from "@otunes/convex/_generated/dataModel"
const warmedAudioIds = new Set<string>()
class IntentRejected extends Error {}
const KNOWN_INTENTS = new Set([
"playMusic",
"warmupAudio",
"addToPlaylist",
"addToUpNext",
"clearUpNext",
"createPlaylist",
"createStation",
"updateAffinity",
"transport",
"openMusic",
])
type MusicSource = {
kind: string
id: string
}
function readString(value: unknown) {
return typeof value === "string" && value.trim() ? value : null
}
function readSources(value: unknown): MusicSource[] {
if (!Array.isArray(value)) {
return []
}
return value.flatMap((entry) => {
if (!entry || typeof entry !== "object") {
return []
}
const source = entry as { kind?: unknown; id?: unknown }
if (typeof source.kind !== "string" || typeof source.id !== "string") {
return []
}
if (!source.kind || !source.id) {
return []
}
return [{ kind: source.kind, id: source.id }]
})
}
function shuffleChoice(value: unknown, fallback: boolean) {
if (value === "songs") return true
if (value === "off") return false
if (value == null) return fallback
throw new IntentRejected("Shuffle must be Off or Songs.")
}
function repeatChoice(value: unknown): RepeatMode | null {
if (value == null) return null
if (value === "none") return "none"
if (value === "one") return "once"
if (value === "all") return "always"
throw new IntentRejected("Repeat must be None, One, or All.")
}
function ensureActive(invocation: AppIntentInvocation) {
const deadline = invocation.params.deadline
if (typeof deadline === "number" && Date.now() >= deadline) {
throw new IntentRejected("This request expired. Please try again.")
}
}
function isTransient(error: unknown) {
const message = (
error instanceof Error ? error.message : String(error)
).toLowerCase()
return (
message.includes("not authenticated") ||
message.includes("network") ||
message.includes("fetch") ||
message.includes("connection") ||
message.includes("timed out") ||
message.includes("timeout")
)
}
function songEntity(song: {
id: string
title: string
artistName: string
artistId: string
albumTitle: string
albumId: string
durationSeconds: number
genres?: string
year?: number
track?: number
diskNumber?: number | null
favorite?: boolean
}): AppIntentEntity {
return {
id: song.id,
title: song.title,
subtitle: song.artistName,
synonyms: song.artistName ? [song.artistName] : undefined,
metadata: {
artistName: song.artistName,
artistId: song.artistId,
albumTitle: song.albumTitle,
albumId: song.albumId,
duration: String(song.durationSeconds),
genres: song.genres ?? "",
year: song.year ? String(song.year) : "",
track: song.track == null ? "" : String(song.track),
disk: song.diskNumber == null ? "" : String(song.diskNumber),
favorite: song.favorite ? "1" : "0",
},
}
}
export function AppIntentBridge() {
const scope = useCacheScope()
const store = useMemo(
() => getPlaybackStore(scope === ANONYMOUS_CACHE_SCOPE ? null : scope),
[scope]
)
const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot)
const user = useQuery(api.auth.currentUser)
return user && snapshot.hydrated ? <ReadyAppIntentBridge key={scope} /> : null
}
function ReadyAppIntentBridge() {
const convex = useConvex()
const cacheScope = useCacheScope()
const playback = usePlayback()
const user = useQuery(api.auth.currentUser)
const navigation = useAppNavigation()
const favorites = useQuery(api.favorites.getUserFavorites)
const catalogUserKey = user ? JSON.stringify([user._id, favorites]) : null
const store = useMemo(
() =>
getPlaybackStore(
cacheScope === ANONYMOUS_CACHE_SCOPE ? null : cacheScope
),
[cacheScope]
)
const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot)
const handledIds = useRef<Set<string> | null>(null)
const publishChain = useRef(Promise.resolve())
const publishGeneration = useRef(0)
const playbackRef = useRef(playback)
playbackRef.current = playback
useEffect(() => {
if (!AppIntents.isAvailable() || !user) return
const generation = ++publishGeneration.current
let stopped = false
let refreshing = false
const refresh = () => {
if (refreshing || stopped) return
refreshing = true
publishChain.current = publishChain.current
.catch(() => undefined)
.then(async () => {
for (const kind of ["artist", "album", "song", "playlist"] as const) {
const entities: AppIntentEntity[] = []
let cursor: string | null = null
do {
const result: {
page: AppIntentEntity[]
isDone: boolean
continueCursor: string
} = await convex.query(api.library.intentCatalogPage, {
kind,
paginationOpts: { cursor, numItems: 200 },
})
if (stopped || generation !== publishGeneration.current) return
entities.push(...result.page)
cursor = result.isDone ? null : result.continueCursor
} while (cursor !== null)
await publishMusicCatalog(kind, entities)
}
})
.catch((error) =>
console.warn("Could not publish music catalog.", error)
)
.finally(() => {
refreshing = false
})
trackMusicCatalogSync(publishChain.current)
}
refresh()
const subscription = AppState.addEventListener("change", (state) => {
if (state === "active") refresh()
})
const timer = setInterval(() => {
if (AppState.currentState === "active") refresh()
}, 5 * 60_000)
return () => {
stopped = true
++publishGeneration.current
subscription.remove()
clearInterval(timer)
}
}, [convex, cacheScope, catalogUserKey])
const currentSongId = playback.queueSongIds[0] ?? null
const currentSong = playback.currentSong
useEffect(() => {
if (!snapshot.hydrated || !AppIntents.isAvailable()) {
return
}
if (!currentSongId) {
void publishMusicCatalog("nowPlaying", []).catch((error) => {
console.warn("Could not clear the current song.", error)
})
return
}
if (!currentSong || currentSong.id !== currentSongId) {
return
}
void publishMusicCatalog("nowPlaying", [
songEntity({
id: currentSong.id,
title: currentSong.title,
artistName: currentSong.artist.name,
artistId: currentSong.artist.id,
albumTitle: currentSong.album.title,
albumId: currentSong.album.id,
durationSeconds: currentSong.durationSeconds,
}),
]).catch((error) => {
console.warn("Could not publish the current song.", error)
})
}, [currentSong, currentSongId, snapshot.hydrated])
AppIntents.useAppIntents(async (pendingIntents) => {
if (!handledIds.current) {
handledIds.current = await loadHandledIntentIds()
}
const handled = handledIds.current
for (const invocation of pendingIntents) {
if (handled.has(invocation.id)) {
const token = readString(invocation.params.completionToken)
if (token) await completeMusicInvocation(token, null)
await AppIntents.removePendingInvocationAsync(invocation.id)
continue
}
if (!KNOWN_INTENTS.has(invocation.name)) {
await AppIntents.removePendingInvocationAsync(invocation.id)
continue
}
const token = readString(invocation.params.completionToken)
try {
ensureActive(invocation)
await performInvocation(invocation)
if (
["playMusic", "warmupAudio", "transport", "createStation"].includes(
invocation.name
)
) {
const id = store.getState().queue[0]
const song = playbackRef.current.currentSong
if (!id) await publishMusicCatalog("nowPlaying", [])
else if (song?.id === id)
await publishMusicCatalog("nowPlaying", [
songEntity({
id: song.id,
title: song.title,
artistName: song.artist.name,
artistId: song.artist.id,
albumTitle: song.album.title,
albumId: song.album.id,
durationSeconds: song.durationSeconds,
}),
])
}
await rememberHandledIntentId(handled, invocation.id)
if (token) await completeMusicInvocation(token, null)
await AppIntents.removePendingInvocationAsync(invocation.id)
} catch (error) {
if (token) {
await completeMusicInvocation(
token,
error instanceof Error ? error.message : "oTunes couldn't do that."
)
}
if (token || error instanceof IntentRejected || !isTransient(error)) {
const message =
error instanceof Error ? error.message : "oTunes couldn't do that."
if (!(error instanceof IntentRejected) || message) {
showError(message)
}
try {
await rememberHandledIntentId(handled, invocation.id)
await AppIntents.removePendingInvocationAsync(invocation.id)
} catch (removeError) {
console.warn(
"App Intent remains pending",
invocation.id,
removeError
)
}
continue
}
console.warn("App Intent remains pending", invocation.id, error)
}
}
async function songIdsFor(kind: string, id: string) {
if (kind === "song") {
return [id as Id<"songs">]
}
if (kind === "album") {
return fetchCachedQuery(
convex,
cacheScope,
api.playlists.getAlbumSongIds,
{
albumId: id as Id<"albums">,
}
)
}
if (kind === "artist") {
return fetchCachedQuery(
convex,
cacheScope,
api.playlists.getOrderedArtistSongIds,
{ artistId: id as Id<"artists"> }
)
}
if (kind === "playlist") {
if (id === FAVORITES_PLAYLIST_ID) {
const favorites = await fetchCachedQuery(
convex,
cacheScope,
api.favorites.getUserFavorites,
{}
)
return favorites.favoriteSongs
}
return fetchCachedQuery(
convex,
cacheScope,
api.playlists.getPlaylistSongIds,
{ playlistId: id as Id<"playlists"> }
)
}
throw new IntentRejected("Choose a song, album, artist, or playlist.")
}
async function uniqueSongIds(sources: MusicSource[]) {
const ids: Id<"songs">[] = []
for (const source of sources) {
ids.push(...(await songIdsFor(source.kind, source.id)))
}
return [...new Set(ids)]
}
async function performInvocation(invocation: AppIntentInvocation) {
const actions = playbackRef.current
switch (invocation.name) {
case "openMusic": {
const kind = readString(invocation.params.kind)
const id = readString(invocation.params.id)
if (!id || !kind) throw new IntentRejected("Choose music to open.")
if (kind === "song") {
const song = await convex.query(api.library.getSong, {
id: id as Id<"songs">,
})
if (!song)
throw new IntentRejected("This song is no longer available.")
navigation.push(`/album/${song.album}`)
} else if (kind === "playlist" && id === FAVORITES_PLAYLIST_ID) {
navigation.push("/playlist/favorites")
} else if (["album", "artist", "playlist"].includes(kind)) {
navigation.push(`/${kind}/${id}`)
} else throw new IntentRejected("Unknown music type.")
return
}
case "playMusic":
await playMusic(invocation)
if (!["next", "tail"].includes(String(invocation.params.queue))) {
ensureActive(invocation)
await playbackRef.current.waitForPlaybackReady(true)
}
return
case "warmupAudio":
await warmup(invocation)
ensureActive(invocation)
await playbackRef.current.waitForPlaybackReady(false)
warmedAudioIds.add(invocation.id)
return
case "addToPlaylist":
await addToPlaylist(invocation)
return
case "addToUpNext":
await addToUpNext(invocation)
return
case "clearUpNext":
ensureActive(invocation)
await actions.clearUpNext()
return
case "createPlaylist":
await createPlaylist(invocation)
return
case "createStation":
await createStation(invocation)
ensureActive(invocation)
await playbackRef.current.waitForPlaybackReady(true)
return
case "updateAffinity":
await updateAffinity(invocation)
return
case "transport":
await transport(invocation)
if (store.getState().queue.length > 0) {
const command = invocation.params.command
await playbackRef.current.waitForPlaybackReady(
command === "resume"
? true
: command === "pause"
? false
: undefined
)
}
return
default:
return
}
}
async function playMusic(invocation: AppIntentInvocation) {
const actions = playbackRef.current
const queue = readString(invocation.params.queue) ?? "now"
const warmupId = readString(invocation.params.warmupId)
const repeat = repeatChoice(invocation.params.repeat)
if (repeat) {
ensureActive(invocation)
await actions.setRepeatMode(repeat)
}
if (queue === "next" || queue === "tail") {
const kind = readString(invocation.params.kind)
const id = readString(invocation.params.id)
if (!kind || !id) {
throw new IntentRejected("Choose music to add to Up Next.")
}
const shuffled = shuffleChoice(
invocation.params.shuffle,
actions.shuffleEnabled
)
if (shuffled !== actions.shuffleEnabled) {
ensureActive(invocation)
await actions.setShuffleEnabled(shuffled)
}
const ids = await songIdsFor(kind, id)
if (ids.length === 0) {
throw new IntentRejected("Nothing to add to Up Next.")
}
if (queue === "next") {
ensureActive(invocation)
await actions.addToQueueNext(ids)
} else {
ensureActive(invocation)
await actions.addToQueueLast(ids)
}
return
}
if (warmupId && warmedAudioIds.has(warmupId)) {
const shuffled = shuffleChoice(
invocation.params.shuffle,
actions.shuffleEnabled
)
if (shuffled !== actions.shuffleEnabled) {
ensureActive(invocation)
await actions.setShuffleEnabled(shuffled)
}
ensureActive(invocation)
actions.setIsPlaying(true)
return
}
const kind = readString(invocation.params.kind) ?? "resume"
if (kind === "resume") {
const shuffled = shuffleChoice(
invocation.params.shuffle,
actions.shuffleEnabled
)
if (shuffled !== actions.shuffleEnabled) {
ensureActive(invocation)
await actions.setShuffleEnabled(shuffled)
}
if (actions.queueSongIds.length === 0) {
const favorites = await fetchCachedQuery(
convex,
cacheScope,
api.favorites.getUserFavorites,
{}
)
if (favorites.favoriteSongs.length === 0) {
throw new IntentRejected(
"Nothing is queued, and your favorites are empty."
)
}
if (shuffled) {
ensureActive(invocation)
await actions.playShuffled(favorites.favoriteSongs)
} else {
ensureActive(invocation)
await actions.playInOrder(favorites.favoriteSongs)
}
return
}
ensureActive(invocation)
actions.setIsPlaying(true)
return
}
const id = readString(invocation.params.id)
if (!id) {
throw new IntentRejected("Choose music to play.")
}
const shuffled = shuffleChoice(
invocation.params.shuffle,
actions.shuffleEnabled
)
if (kind === "song") {
const song = await fetchCachedQuery(
convex,
cacheScope,
api.library.getSong,
{
id: id as Id<"songs">,
}
)
if (!song) {
throw new IntentRejected("That song is no longer in your library.")
}
const albumSongIds = await fetchCachedQuery(
convex,
cacheScope,
api.playlists.getAlbumSongIds,
{ albumId: song.album }
)
ensureActive(invocation)
await actions.startFromSong(
song._id,
albumSongIds.length > 0 ? albumSongIds : [song._id],
shuffled,
true
)
return
}
const ids = await songIdsFor(kind, id)
if (ids.length === 0) {
throw new IntentRejected("Nothing to play.")
}
if (shuffled) {
ensureActive(invocation)
await actions.playShuffled(ids)
} else {
ensureActive(invocation)
await actions.playInOrder(ids)
}
}
async function warmup(invocation: AppIntentInvocation) {
const kind = readString(invocation.params.kind)
const id = readString(invocation.params.id)
if (!kind || !id) {
throw new IntentRejected("Choose music to get ready.")
}
const shuffled = shuffleChoice(invocation.params.shuffle, false)
if (kind === "song") {
const song = await fetchCachedQuery(
convex,
cacheScope,
api.library.getSong,
{
id: id as Id<"songs">,
}
)
if (!song) {
throw new IntentRejected("That song is no longer in your library.")
}
const albumSongIds = await fetchCachedQuery(
convex,
cacheScope,
api.playlists.getAlbumSongIds,
{ albumId: song.album }
)
ensureActive(invocation)
await playbackRef.current.startFromSong(
song._id,
albumSongIds.length > 0 ? albumSongIds : [song._id],
shuffled,
false
)
} else {
const ids = await songIdsFor(kind, id)
if (ids.length === 0) {
throw new IntentRejected("Nothing to get ready.")
}
ensureActive(invocation)
await playbackRef.current.prepareQueue(ids, shuffled)
}
}
async function addToPlaylist(invocation: AppIntentInvocation) {
const playlistId = readString(invocation.params.playlistId)
const sources = readSources(invocation.params.sources)
if (!playlistId || sources.length === 0) {
throw new IntentRejected("Choose music and a playlist.")
}
const songIds = await uniqueSongIds(sources)
if (songIds.length === 0) {
throw new IntentRejected("Those items have no songs to add.")
}
if (playlistId === FAVORITES_PLAYLIST_ID) {
for (const source of sources) {
if (source.kind === "song") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteSong, {
songId: source.id as Id<"songs">,
})
} else if (source.kind === "album") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteAlbum, {
albumId: source.id as Id<"albums">,
})
} else if (source.kind === "artist") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteArtist, {
artistId: source.id as Id<"artists">,
})
} else if (source.kind === "playlist") {
const ids = await songIdsFor(source.kind, source.id)
if (ids.length > 0) {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteSongs, {
songIds: ids,
})
}
} else {
throw new IntentRejected(
"Choose a song, album, artist, or playlist."
)
}
}
return
}
ensureActive(invocation)
await convex.mutation(api.playlists.addSongsToPlaylist, {
playlistId: playlistId as Id<"playlists">,
songIds,
})
}
async function addToUpNext(invocation: AppIntentInvocation) {
const sources = readSources(invocation.params.sources)
if (sources.length === 0) {
throw new IntentRejected("Choose music to add to Up Next.")
}
const ids = await uniqueSongIds(sources)
if (ids.length === 0) {
throw new IntentRejected("Nothing to add to Up Next.")
}
const position =
readString(invocation.params.position) === "last" ? "last" : "next"
if (position === "last") {
ensureActive(invocation)
await playbackRef.current.addToQueueLast(ids)
} else {
ensureActive(invocation)
await playbackRef.current.addToQueueNext(ids)
}
}
async function createPlaylist(invocation: AppIntentInvocation) {
const name = readString(invocation.params.name)
if (!name) {
throw new IntentRejected("A playlist needs a name.")
}
const songIds = await uniqueSongIds(
readSources(invocation.params.sources)
)
ensureActive(invocation)
await convex.mutation(api.playlists.createPlaylist, {
name,
songIds,
invocationId: invocation.id,
})
}
async function createStation(invocation: AppIntentInvocation) {
const artistId = readString(invocation.params.artistId)
if (!artistId) {
throw new IntentRejected("Nothing is playing in oTunes.")
}
const ids = await songIdsFor("artist", artistId)
if (ids.length === 0)
throw new IntentRejected("This artist has no songs to play.")
ensureActive(invocation)
await playbackRef.current.playShuffled(ids)
}
async function updateAffinity(invocation: AppIntentInvocation) {
const kind = readString(invocation.params.kind)
const id = readString(invocation.params.id)
const state = readString(invocation.params.state)
if (!kind || !id || (state !== "like" && state !== "unset")) {
throw new IntentRejected(
"oTunes can love or unlike a song, album, or artist."
)
}
if (kind === "playlist") {
throw new IntentRejected("oTunes can love songs, albums, and artists.")
}
if (state === "like") {
if (kind === "song") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteSong, {
songId: id as Id<"songs">,
})
} else if (kind === "album") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteAlbum, {
albumId: id as Id<"albums">,
})
} else if (kind === "artist") {
ensureActive(invocation)
await convex.mutation(api.favorites.favoriteArtist, {
artistId: id as Id<"artists">,
})
} else {
throw new IntentRejected(
"oTunes can love songs, albums, and artists."
)
}
return
}
if (kind === "song") {
ensureActive(invocation)
await convex.mutation(api.favorites.unfavoriteSong, {
songId: id as Id<"songs">,
})
} else if (kind === "album") {
ensureActive(invocation)
await convex.mutation(api.favorites.unfavoriteAlbum, {
albumId: id as Id<"albums">,
})
} else if (kind === "artist") {
ensureActive(invocation)
await convex.mutation(api.favorites.unfavoriteArtist, {
artistId: id as Id<"artists">,
})
} else {
throw new IntentRejected("oTunes can love songs, albums, and artists.")
}
}
async function transport(invocation: AppIntentInvocation) {
const actions = playbackRef.current
const command = readString(invocation.params.command)
if (command === "pause") {
ensureActive(invocation)
actions.setIsPlaying(false)
return
}
if (command === "resume") {
if (actions.queueSongIds.length === 0) {
throw new IntentRejected("Nothing is queued in oTunes.")
}
ensureActive(invocation)
actions.setIsPlaying(true)
return
}
if (command === "next") {
ensureActive(invocation)
await actions.skipNext()
return
}
if (command === "previous") {
ensureActive(invocation)
await actions.skipPrevious()
return
}
throw new IntentRejected("oTunes doesn't know that playback control.")
}
})
return null
}