3.6 KiB
Siri and Shortcuts
This integration uses Expo 58 inline modules and expo-app-intents. Rebuild the native app after changing Swift declarations or registrations. An OTA JavaScript update cannot add these capabilities.
Playback and library changes open oTunes because they need its authenticated React runtime. Swift dispatches a request and waits for an app-owned completion acknowledgment. Playback waits for the native audio player to load the requested track; warmup waits for it to load while paused. Errors reach Siri, and requests that have expired are discarded before starting a side effect. Native catalog reads do not open the app.
The full entity catalog lives in Application Support. Expo's UserDefaults catalog holds at most 100 suggestions per kind, with favorites first, and mirrors those suggestions into Spotlight. Siri's native queries search the full disk catalog.
Sync is incremental. The app subscribes to intentCatalog.head, the newest insert, rename or deletion per kind, and fetches a kind only when it moves past the cursor stored in AsyncStorage. intentCatalog.page then returns records created after the cursor plus renames and deletions from the intentCatalogChanges log. The log keeps 30 days; older cursors, or more than 2,000 changes, rebuild that kind from scratch. Favorites are stamped onto records on device from the favorites subscription, so liking a song costs no catalog queries. Playlists come from the live intentCatalog.playlists query. Code lives in components/app-intents/: catalog-sync.ts, now-playing.ts, and dispatch.ts.
Songs, albums, artists, and playlists have Spotlight open intents and on-screen entity associations. Associations require iOS 18.4 and Xcode 27; Spotlight indexing requires iOS 18. Playback donations are made after the player starts, preserve shuffle, and resolve real catalog entities. Removed records trigger donation cleanup. Sign-out clears catalogs, Spotlight entries, donations, and pending invocations. On iOS 27, the query types also handle system requests to rebuild Spotlight indexes.
Audio schema intents require Xcode 27 and iOS 27. Custom intents remain available on earlier supported versions and remain visible on iOS 27 because intent discovery metadata must be a compile-time constant.
Backend rollout
Deploy the companion Convex changes before installing the new mobile build:
intentCatalog.head,intentCatalog.pageandintentCatalog.playlistssupply the entity catalog. Library mutations record renames and deletions inintentCatalogChanges, pruned daily.appIntentPlaylistsrecords playlist-creation request IDs in the same transaction as creation. Replaying a request returns the original playlist ID.playlists.createPlaylistaccepts an optionalinvocationId; existing callers can omit it.
Verification
Run from the repository root:
pnpm --filter @otunes/mobile typecheck
pnpm --filter @otunes/convex typecheck
node --test apps/mobile/lib/app-intents.test.cjs packages/convex/convex/app-intent-playlists.test.cjs
Build iOS with Xcode and verify the app target's ExtractAppIntentsMetadata phase. TypeScript checks alone do not validate Swift declarations or Apple's schema contracts.
On a suitable device, verify cold and warm playback, paused warmup followed by playback, offline errors, request expiry, playlist replay, and a saved shortcut after upgrading. Check entity resolution after rename/delete and sign-out. Verify Spotlight opening, on-screen requests, and donations separately; metadata extraction does not establish system discovery or successful runtime execution.