Files
faceclaw/app/native/spotify-web-api.ts

475 lines
18 KiB
TypeScript

/**
* 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<string, string>; body?: string },
) => Promise<{ status: number; text(): Promise<string> }>;
/** Hands out a current access token, refreshing it when expired or when forced (after a 401). */
export type SpotifyTokenSource = {
accessToken(forceRefresh: boolean): Promise<string>;
};
/** 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<string, string | number | boolean | undefined>;
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<SpotifyPlayback | null> {
const raw = await this.request("GET", "/me/player", { query: { additional_types: "episode" } });
return raw ? parsePlayback(raw) : null;
}
async queue(): Promise<SpotifyQueue> {
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<SpotifyDevice[]> {
const raw = await this.request("GET", "/me/player/devices");
return asArray(raw?.devices).map(parseDevice).filter(isPresent);
}
async play(request: SpotifyPlayRequest = {}, deviceId = ""): Promise<void> {
const body: Record<string, unknown> = {};
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<void> {
await this.request("PUT", "/me/player/pause");
}
async next(): Promise<void> {
await this.request("POST", "/me/player/next");
}
async previous(): Promise<void> {
await this.request("POST", "/me/player/previous");
}
async setShuffle(on: boolean): Promise<void> {
await this.request("PUT", "/me/player/shuffle", { query: { state: on } });
}
async setRepeat(mode: SpotifyRepeat): Promise<void> {
await this.request("PUT", "/me/player/repeat", { query: { state: mode } });
}
async setVolume(percent: number, deviceId = ""): Promise<void> {
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<void> {
await this.request("PUT", "/me/player", { body: { device_ids: [deviceId], play } });
}
async me(): Promise<SpotifyUser> {
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<boolean[]> {
const raw = await this.request("GET", "/me/library/contains", { query: { uris: uris.join(",") } });
return asArray(raw).map(Boolean);
}
async saveToLibrary(uris: string[]): Promise<void> {
await this.request("PUT", "/me/library", { query: { uris: uris.join(",") } });
}
async removeFromLibrary(uris: string[]): Promise<void> {
await this.request("DELETE", "/me/library", { query: { uris: uris.join(",") } });
}
playlists(): Promise<SpotifyPlaylist[]> {
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<SpotifyItem[]> {
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<SpotifyItem[]> {
return this.collect("/me/tracks", { limit: 50 }, (raw) => asArray(raw?.items).map((entry: any) => parseItem(entry?.track)));
}
savedAlbums(): Promise<SpotifyAlbum[]> {
return this.collect("/me/albums", { limit: 50 }, (raw) => asArray(raw?.items).map((entry: any) => parseAlbum(entry?.album)));
}
albumTracks(albumId: string): Promise<SpotifyItem[]> {
return this.collect(`/albums/${encodeURIComponent(albumId)}/tracks`, { limit: 50 }, (raw) => asArray(raw?.items).map(parseItem));
}
followedArtists(): Promise<SpotifyArtist[]> {
// 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<SpotifyAlbum[]> {
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<SpotifyPlayed[]> {
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<SpotifySearchResults> {
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<T>(
path: string,
query: Query,
parse: (raw: any) => Array<T | null>,
nextOf: (raw: any) => string = (raw) => str(raw?.next),
maxItems = MAX_LIST_ITEMS,
): Promise<T[]> {
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<any> {
const url = path.startsWith("https://") ? path : `${SPOTIFY_API_BASE}${path}${buildQuery(options.query)}`;
const headers: Record<string, string> = { 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<T>(promise: Promise<T>): Promise<T> {
let timer: ReturnType<typeof setTimeout> | null = null;
const timeout = new Promise<never>((_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<T>(value: T | null | undefined): value is T {
return value !== null && value !== undefined;
}