/** * Spotify Web API over HTTPS with the signed-in user's token: the player * (what is playing on any of the user's Spotify Connect devices, and control * of it), the user's library, and search, normalized into the small shapes * the Music app uses. No NativeScript imports, so the Node tests drive it with * a fake fetch. * * Every personal client ID is a development-mode app, which since February * 2026 means: the client ID's owner needs Premium, playback control needs * Premium, at most five allowlisted users, only owned or collaborative * playlists list their items, no batch lookups, and search and artist albums * return at most 10 results per page. */ export const SPOTIFY_API_BASE = "https://api.spotify.com/v1"; const HTTP_TIMEOUT_MS = 12_000; /** The most a library listing gathers (a page is 50); enough to scroll through on the glasses. */ const MAX_LIST_ITEMS = 500; /** The subset of fetch this client needs (fetchTextWithUserAgent in the app). */ export type SpotifyFetch = ( url: string, init: { method: string; headers: Record; body?: string }, ) => Promise<{ status: number; text(): Promise }>; /** Hands out a current access token, refreshing it when expired or when forced (after a 401). */ export type SpotifyTokenSource = { accessToken(forceRefresh: boolean): Promise; }; /** A failed request; `reason` is Spotify's player error code (NO_ACTIVE_DEVICE, PREMIUM_REQUIRED, ...). */ export class SpotifyApiError extends Error { constructor( message: string, readonly status: number, readonly reason = "", ) { super(message); this.name = "SpotifyApiError"; } } export type SpotifyImage = { url: string; width: number; height: number }; export type SpotifyItem = { uri: string; type: "track" | "episode"; name: string; /** Track artists, comma-joined; for an episode, its show. */ artists: string; /** The track's album; for an episode, its show. "" when the API leaves it out (album track listings). */ album: string; durationMs: number; images: SpotifyImage[]; }; export type SpotifyDevice = { id: string; name: string; /** "Smartphone", "Computer", "Speaker", ... */ type: string; active: boolean; /** Restricted devices accept no Web API commands. */ restricted: boolean; /** -1 when the device reports none. */ volumePercent: number; supportsVolume: boolean; }; export type SpotifyRepeat = "off" | "context" | "track"; export type SpotifyPlayback = { device: SpotifyDevice | null; playing: boolean; progressMs: number; shuffle: boolean; repeat: SpotifyRepeat; /** The playlist / album / artist playing from; "" for none (a queue of single tracks). */ contextUri: string; /** null during an ad, between items, or for content the API does not describe. */ item: SpotifyItem | null; /** "track", "episode", "ad" or "unknown". */ playingType: string; /** The player actions the context forbids, as Spotify names them: pausing, resuming, skipping_next, ... */ disallows: string[]; }; export type SpotifyQueue = { current: SpotifyItem | null; upcoming: SpotifyItem[] }; export type SpotifyUser = { id: string; displayName: string; product: string }; export type SpotifyPlaylist = { id: string; uri: string; name: string; ownerId: string; ownerName: string; collaborative: boolean; total: number; }; export type SpotifyAlbum = { id: string; uri: string; name: string; artists: string }; export type SpotifyArtist = { id: string; uri: string; name: string }; /** A played track and the context it played from ("" when none). */ export type SpotifyPlayed = { item: SpotifyItem; contextUri: string }; export type SpotifySearchResults = { tracks: SpotifyItem[]; albums: SpotifyAlbum[]; artists: SpotifyArtist[]; playlists: SpotifyPlaylist[]; }; export type SpotifySearchType = "track" | "album" | "artist" | "playlist"; /** * What to play: a context (playlist, album, artist, show) optionally starting * at one of its items, or a list of track URIs. Empty resumes the current * playback. */ export type SpotifyPlayRequest = { contextUri?: string; uris?: string[]; offsetUri?: string; offsetPosition?: number; }; type Query = Record; export class SpotifyClient { constructor( private readonly fetchImpl: SpotifyFetch, private readonly tokens: SpotifyTokenSource, ) {} /** The current playback on whichever device is active; null when nothing is. */ async playback(): Promise { const raw = await this.request("GET", "/me/player", { query: { additional_types: "episode" } }); return raw ? parsePlayback(raw) : null; } async queue(): Promise { const raw = await this.request("GET", "/me/player/queue"); return { current: parseItem(raw?.currently_playing), upcoming: asArray(raw?.queue).map(parseItem).filter(isPresent), }; } async devices(): Promise { const raw = await this.request("GET", "/me/player/devices"); return asArray(raw?.devices).map(parseDevice).filter(isPresent); } async play(request: SpotifyPlayRequest = {}, deviceId = ""): Promise { const body: Record = {}; if (request.contextUri) body.context_uri = request.contextUri; if (request.uris?.length) body.uris = request.uris; if (request.offsetUri) body.offset = { uri: request.offsetUri }; else if (request.offsetPosition !== undefined) body.offset = { position: request.offsetPosition }; await this.request("PUT", "/me/player/play", { query: { device_id: deviceId || undefined }, body }); } async pause(): Promise { await this.request("PUT", "/me/player/pause"); } async next(): Promise { await this.request("POST", "/me/player/next"); } async previous(): Promise { await this.request("POST", "/me/player/previous"); } async setShuffle(on: boolean): Promise { await this.request("PUT", "/me/player/shuffle", { query: { state: on } }); } async setRepeat(mode: SpotifyRepeat): Promise { await this.request("PUT", "/me/player/repeat", { query: { state: mode } }); } async setVolume(percent: number, deviceId = ""): Promise { const volume = Math.max(0, Math.min(100, Math.round(percent))); await this.request("PUT", "/me/player/volume", { query: { volume_percent: volume, device_id: deviceId || undefined } }); } /** Move playback to a device (one that shows in devices() but is not active), optionally playing. */ async transfer(deviceId: string, play: boolean): Promise { await this.request("PUT", "/me/player", { body: { device_ids: [deviceId], play } }); } async me(): Promise { const raw = await this.request("GET", "/me"); return { id: str(raw?.id), displayName: str(raw?.display_name) || str(raw?.id), product: str(raw?.product) }; } /** Whether each URI is in the user's library (Liked Songs for tracks). */ async libraryContains(uris: string[]): Promise { const raw = await this.request("GET", "/me/library/contains", { query: { uris: uris.join(",") } }); return asArray(raw).map(Boolean); } async saveToLibrary(uris: string[]): Promise { await this.request("PUT", "/me/library", { query: { uris: uris.join(",") } }); } async removeFromLibrary(uris: string[]): Promise { await this.request("DELETE", "/me/library", { query: { uris: uris.join(",") } }); } playlists(): Promise { return this.collect("/me/playlists", { limit: 50 }, (raw) => asArray(raw?.items).map(parsePlaylist)); } /** Only playlists the user owns or collaborates on list their items (403 otherwise). */ playlistItems(playlistId: string): Promise { return this.collect(`/playlists/${encodeURIComponent(playlistId)}/items`, { limit: 50, additional_types: "track,episode" }, (raw) => asArray(raw?.items).map((entry: any) => parseItem(entry?.item ?? entry?.track))); } savedTracks(): Promise { return this.collect("/me/tracks", { limit: 50 }, (raw) => asArray(raw?.items).map((entry: any) => parseItem(entry?.track))); } savedAlbums(): Promise { return this.collect("/me/albums", { limit: 50 }, (raw) => asArray(raw?.items).map((entry: any) => parseAlbum(entry?.album))); } albumTracks(albumId: string): Promise { return this.collect(`/albums/${encodeURIComponent(albumId)}/tracks`, { limit: 50 }, (raw) => asArray(raw?.items).map(parseItem)); } followedArtists(): Promise { // Cursor-paged, with the page wrapped in an "artists" object. return this.collect("/me/following", { type: "artist", limit: 50 }, (raw) => asArray(raw?.artists?.items).map(parseArtist), (raw) => str(raw?.artists?.next)); } artistAlbums(artistId: string): Promise { return this.collect(`/artists/${encodeURIComponent(artistId)}/albums`, { include_groups: "album,single,compilation", limit: 10 }, (raw) => asArray(raw?.items).map(parseAlbum), undefined, 100); } /** Recently played tracks, newest first (one page: the API keeps only the last 50). */ async recentlyPlayed(): Promise { const raw = await this.request("GET", "/me/player/recently-played", { query: { limit: 50 } }); return asArray(raw?.items) .map((entry: any) => { const item = parseItem(entry?.track); return item ? { item, contextUri: str(entry?.context?.uri) } : null; }) .filter(isPresent); } async search(query: string, types: SpotifySearchType[], limit = 5): Promise { const raw = await this.request("GET", "/search", { query: { q: query, type: types.join(","), limit: Math.max(1, Math.min(10, Math.round(limit))) }, }); return { tracks: asArray(raw?.tracks?.items).map(parseItem).filter(isPresent), albums: asArray(raw?.albums?.items).map(parseAlbum).filter(isPresent), artists: asArray(raw?.artists?.items).map(parseArtist).filter(isPresent), // Search results include nulls for playlists the API can no longer return. playlists: asArray(raw?.playlists?.items).map(parsePlaylist).filter(isPresent), }; } /** Gather a paged listing by following its `next` links, up to maxItems. */ private async collect( path: string, query: Query, parse: (raw: any) => Array, nextOf: (raw: any) => string = (raw) => str(raw?.next), maxItems = MAX_LIST_ITEMS, ): Promise { const items: T[] = []; let raw = await this.request("GET", path, { query }); for (;;) { for (const item of parse(raw)) if (item) items.push(item); const next = nextOf(raw); if (!next || items.length >= maxItems) return items.slice(0, maxItems); raw = await this.request("GET", next); } } /** * One API call. `path` is relative to the API base, or an absolute `next` * link from a page. Resolves to the parsed JSON body (null when empty); * a 401 refreshes the token and retries once. */ private async request(method: string, path: string, options: { query?: Query; body?: unknown } = {}): Promise { const url = path.startsWith("https://") ? path : `${SPOTIFY_API_BASE}${path}${buildQuery(options.query)}`; const headers: Record = { Accept: "application/json" }; if (options.body !== undefined) headers["Content-Type"] = "application/json"; // A command without a body still sends an empty one: Spotify answers a // PUT or POST with no Content-Length with 411. const body = options.body !== undefined ? JSON.stringify(options.body) : method === "GET" ? undefined : ""; for (let attempt = 0; ; attempt++) { const authorization = `Bearer ${await this.tokens.accessToken(attempt > 0)}`; const response = await withTimeout(this.fetchImpl(url, { method, headers: { ...headers, Authorization: authorization }, body })); const text = await withTimeout(response.text()); if (response.status === 401 && attempt === 0) continue; if (response.status >= 200 && response.status < 300) { if (!text.trim()) return null; try { return JSON.parse(text); } catch { // Commands answer 200 with a snapshot id or plain text; nothing to read. return null; } } throw apiError(response.status, text); } } } /** Form / query encoding (not URLSearchParams, which the NativeScript runtime mishandles). */ export function buildQuery(query: Query | undefined): string { if (!query) return ""; const parts = Object.keys(query) .filter((key) => query[key] !== undefined && query[key] !== "") .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(String(query[key]))}`); return parts.length ? `?${parts.join("&")}` : ""; } async function withTimeout(promise: Promise): Promise { let timer: ReturnType | null = null; const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new SpotifyApiError("Spotify didn't answer. Check the phone's connection.", 0)), HTTP_TIMEOUT_MS); }); try { return await Promise.race([promise, timeout]); } catch (error) { if (error instanceof SpotifyApiError) throw error; throw new SpotifyApiError(`Can't reach Spotify: ${(error as Error)?.message ?? error}`, 0); } finally { if (timer) clearTimeout(timer); } } /** A message for the glasses from Spotify's error body ({error: {status, message, reason}}). */ function apiError(status: number, body: string): SpotifyApiError { let message = ""; let reason = ""; try { const parsed = JSON.parse(body); message = str(parsed?.error?.message ?? parsed?.error_description); reason = str(parsed?.error?.reason); } catch { // Not JSON (a gateway error page). } switch (reason) { case "NO_ACTIVE_DEVICE": return new SpotifyApiError("Spotify isn't open on any device. Open Spotify on your phone, then try again.", status, reason); case "PREMIUM_REQUIRED": return new SpotifyApiError("Controlling Spotify playback needs Spotify Premium.", status, reason); } if (status === 401) return new SpotifyApiError("Spotify no longer accepts this sign-in. Sign in again from the Music app menu.", status, reason); if (status === 403 && /registered|developer dashboard/i.test(message)) { return new SpotifyApiError("This Spotify account isn't on the client ID's user list (Developer Dashboard > User Management).", status, reason); } if (status === 429) return new SpotifyApiError("Spotify is limiting requests; try again in a minute.", status, reason); return new SpotifyApiError(message ? `Spotify: ${message}` : `Spotify error (HTTP ${status}).`, status, reason); } export function parsePlayback(raw: any): SpotifyPlayback { const repeat = str(raw?.repeat_state); const disallows = raw?.actions?.disallows; return { device: parseDevice(raw?.device), playing: raw?.is_playing === true, progressMs: num(raw?.progress_ms, 0), shuffle: raw?.shuffle_state === true, repeat: repeat === "context" || repeat === "track" ? repeat : "off", contextUri: str(raw?.context?.uri), item: parseItem(raw?.item), playingType: str(raw?.currently_playing_type) || "unknown", disallows: disallows && typeof disallows === "object" ? Object.keys(disallows).filter((key) => disallows[key] === true) : [], }; } export function parseItem(raw: any): SpotifyItem | null { if (!raw || typeof raw !== "object" || typeof raw.uri !== "string" || !raw.uri) return null; if (raw.type === "episode") { const show = str(raw.show?.name); return { uri: raw.uri, type: "episode", name: str(raw.name), artists: show || str(raw.show?.publisher), album: show, durationMs: num(raw.duration_ms, -1), images: parseImages(raw.images?.length ? raw.images : raw.show?.images), }; } return { uri: raw.uri, type: "track", name: str(raw.name), artists: joinNames(raw.artists), album: str(raw.album?.name), durationMs: num(raw.duration_ms, -1), images: parseImages(raw.album?.images), }; } export function parseDevice(raw: any): SpotifyDevice | null { if (!raw || typeof raw !== "object") return null; const volume = raw.volume_percent; return { id: str(raw.id), name: str(raw.name), type: str(raw.type), active: raw.is_active === true, restricted: raw.is_restricted === true, volumePercent: typeof volume === "number" && Number.isFinite(volume) ? volume : -1, supportsVolume: raw.supports_volume === true, }; } function parsePlaylist(raw: any): SpotifyPlaylist | null { if (!raw || typeof raw !== "object" || !raw.id) return null; return { id: str(raw.id), uri: str(raw.uri) || `spotify:playlist:${raw.id}`, name: str(raw.name), ownerId: str(raw.owner?.id), ownerName: str(raw.owner?.display_name) || str(raw.owner?.id), collaborative: raw.collaborative === true, // `items` replaced the deprecated `tracks` summary in 2026. total: num(raw.items?.total ?? raw.tracks?.total, -1), }; } function parseAlbum(raw: any): SpotifyAlbum | null { if (!raw || typeof raw !== "object" || !raw.id) return null; return { id: str(raw.id), uri: str(raw.uri) || `spotify:album:${raw.id}`, name: str(raw.name), artists: joinNames(raw.artists) }; } function parseArtist(raw: any): SpotifyArtist | null { if (!raw || typeof raw !== "object" || !raw.id) return null; return { id: str(raw.id), uri: str(raw.uri) || `spotify:artist:${raw.id}`, name: str(raw.name) }; } function parseImages(raw: any): SpotifyImage[] { return asArray(raw) .filter((image: any) => image && typeof image.url === "string" && image.url) .map((image: any) => ({ url: image.url, width: num(image.width, 0), height: num(image.height, 0) })); } function joinNames(raw: any): string { return asArray(raw).map((entry: any) => str(entry?.name)).filter(Boolean).join(", "); } function asArray(value: unknown): any[] { return Array.isArray(value) ? value : []; } function str(value: unknown): string { return typeof value === "string" ? value : ""; } function num(value: unknown, fallback: number): number { return typeof value === "number" && Number.isFinite(value) ? value : fallback; } function isPresent(value: T | null | undefined): value is T { return value !== null && value !== undefined; }