upnext-adapter-spotify 0.1.0

package/src/http.ts

@@ -0,0 +1,159 @@
+import { SpotifyError, classifyStatus, errorMessage, retryAfterMs } from './errors.js';
+
+/**
+ * Where the access token comes from — which is to say, not from here.
+ *
+ * This library holds no client id, runs no OAuth flow, opens no browser and
+ * stores no refresh token. That is the same boundary the core draws around
+ * `resolveIntent`: a library that acquires credentials has decided which
+ * provider you use, where the redirect lands and what your token storage looks
+ * like, and none of those are its business.
+ *
+ * So the host supplies a function. It can return a cached token, hit its own
+ * refresh endpoint, or read one out of a config file — the adapter only asks
+ * again when the one it has stops working.
+ */
+export type TokenProvider = () => string | Promise<string>;
+
+export interface SpotifyHttpOptions {
+  getAccessToken: TokenProvider;
+  /** Injected for tests, and for hosts that route their traffic somewhere. */
+  fetch?: typeof globalThis.fetch;
+  baseUrl?: string;
+}
+
+export interface RequestOptions {
+  query?: Record<string, string | number | undefined>;
+  body?: unknown;
+  /** Statuses to answer `null` for instead of throwing. */
+  tolerate?: number[];
+}
+
+/**
+ * One authenticated call to the Web API, with the two failures that actually
+ * happen handled in one place.
+ *
+ * **Expiry.** Tokens last an hour and a queue outlives that easily, so a 401 is
+ * a normal event, not an error. It triggers exactly one re-ask and one retry.
+ * One, because a provider that keeps returning a dead token would otherwise
+ * spin forever, and the second failure is the honest answer: this host cannot
+ * currently authenticate.
+ *
+ * **Concurrency.** Lookahead resolves several entries at once, so several calls
+ * can hit a 401 together. Without the single-flight below they would each fetch
+ * a token, which at best wastes refreshes and at worst trips the host's own
+ * rate limit at the exact moment everything is already failing. A second caller
+ * should adopt the first's work rather than start its own.
+ */
+export class SpotifyHttp {
+  #getAccessToken: TokenProvider;
+  #fetch: typeof globalThis.fetch;
+  #baseUrl: string;
+
+  #token: string | null = null;
+  #fetching: Promise<string> | null = null;
+
+  constructor(options: SpotifyHttpOptions) {
+    this.#getAccessToken = options.getAccessToken;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#baseUrl = (options.baseUrl ?? 'https://api.spotify.com/v1').replace(/\/$/, '');
+  }
+
+  async request(
+    method: 'GET' | 'PUT' | 'POST',
+    path: string,
+    options: RequestOptions = {},
+  ): Promise<unknown> {
+    const response = await this.#send(method, path, options, await this.#authorize(false));
+    if (response.status !== 401) return this.#read(response, options);
+
+    // The token died mid-queue. Get another and try exactly once more.
+    const retry = await this.#send(method, path, options, await this.#authorize(true));
+    return this.#read(retry, options);
+  }
+
+  /** Drop the cached token, so the next call asks the host for a new one. */
+  invalidate(): void {
+    this.#token = null;
+  }
+
+  async #send(
+    method: string,
+    path: string,
+    options: RequestOptions,
+    token: string,
+  ): Promise<Response> {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined && value !== '') url.searchParams.set(key, String(value));
+    }
+
+    const headers: Record<string, string> = { authorization: `Bearer ${token}` };
+    if (options.body !== undefined) headers['content-type'] = 'application/json';
+
+    try {
+      return await this.#fetch(url.toString(), {
+        method,
+        headers,
+        ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+      });
+    } catch (err) {
+      // DNS, a dropped connection, an offline laptop. Not an auth problem and
+      // not something a retry here would fix — the runtime will fall through to
+      // another adapter, which is the correct response to "Spotify is
+      // unreachable right now".
+      throw new SpotifyError(
+        'failed',
+        `could not reach the Spotify Web API: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  async #read(response: Response, options: RequestOptions): Promise<unknown> {
+    // 204 is Spotify's answer to most player commands, and to "nothing is
+    // playing" on the player endpoint. It is a success with nothing in it.
+    if (response.status === 204 || options.tolerate?.includes(response.status)) return null;
+
+    const body = await readJson(response);
+    if (response.ok) return body;
+
+    const reason = classifyStatus(response.status, body);
+    throw new SpotifyError(reason, errorMessage(body, `Spotify returned ${response.status}`), {
+      status: response.status,
+      ...(reason === 'rate-limited'
+        ? { retryAfterMs: retryAfterMs(response.headers.get('retry-after')) }
+        : {}),
+    });
+  }
+
+  async #authorize(force: boolean): Promise<string> {
+    if (!force && this.#token) return this.#token;
+    if (this.#fetching) return this.#fetching;
+
+    this.#fetching = (async () => {
+      const token = await this.#getAccessToken();
+      if (typeof token !== 'string' || !token.trim()) {
+        throw new SpotifyError('unauthorized', 'getAccessToken did not return an access token');
+      }
+      return token.trim();
+    })();
+
+    try {
+      this.#token = await this.#fetching;
+      return this.#token;
+    } finally {
+      this.#fetching = null;
+    }
+  }
+}
+
+/** A body that is not JSON is not worth failing over — the status already said
+ * what happened, and the parsed body only ever adds detail. */
+async function readJson(response: Response): Promise<unknown> {
+  try {
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Two ways to play Spotify, with honestly different capabilities.
+ *
+ * They are separate adapters rather than one adapter with a mode because they
+ * genuinely are not the same backend. One needs no credentials and cannot
+ * search; the other searches a hundred million tracks and needs a token, a
+ * Premium account and a device that is awake. Collapsing that into a single
+ * class would mean a `capabilities` object that is a lie half the time — which
+ * is the exact failure this library exists to avoid.
+ *
+ * Registering both is a reasonable thing to do. They score the same on a
+ * Spotify URI, so the runtime tries one and falls through to the other if it
+ * cannot deliver: the desktop app when it is open, the Web API when it is not.
+ */
+
+export { SpotifyDesktopAdapter } from './desktop.js';
+export type { SpotifyDesktopOptions } from './desktop.js';
+
+export { SpotifyWebAdapter, toSample } from './web.js';
+export type { SpotifyWebOptions } from './web.js';
+
+export { SpotifyHttp } from './http.js';
+export type { TokenProvider, SpotifyHttpOptions, RequestOptions } from './http.js';
+
+export { SpotifyError, classifyStatus, classifyText } from './errors.js';
+export type { SpotifyFailure } from './errors.js';
+
+// Identity helpers, for hosts normalising links a person pasted.
+export { parseSpotifyUri, toSpotifyUri, toSpotifyUrl, isPlayableKind } from './uri.js';
+export type { SpotifyId, SpotifyKind } from './uri.js';
+
+// The pure pieces, exported because they are the parts worth testing and worth
+// reusing if you write a third Spotify backend of your own.
+export { readTrack, searchQuery } from './ref.js';
+export { interpret, initialWatchState } from './sampler.js';
+export type { WatchState, InterpretOptions, Interpretation } from './sampler.js';
+export { BackendWatcher } from './watch.js';
+export type { BackendWatcherDeps } from './watch.js';
+export {
+  parseSample,
+  stateScript,
+  playTrackScript,
+  commandScript,
+  commands,
+  runOsascript,
+  FIELD,
+} from './applescript.js';
+export type { Sample, Osascript } from './applescript.js';
+
+export { embedLookup, readEmbedHtml, clearMetadataCache } from './metadata.js';
+export type { TrackLookup } from './metadata.js';

package/src/metadata.ts

@@ -0,0 +1,167 @@
+import type { MediaRef } from 'upnext-core';
+import { toSpotifyUri, type SpotifyId } from './uri.js';
+
+/**
+ * Turning a bare Spotify id into a title, an artist and a cover, without a
+ * token.
+ *
+ * The desktop backend needs this and the Web API backend does not. Spotify's
+ * AppleScript dictionary can only describe a track once it is *playing*, so a
+ * queue built from share links would show a column of raw URIs right up until
+ * each one started — which is the queue being useless for the one thing a queue
+ * is for, seeing what is coming.
+ *
+ * How it works, stated plainly because it matters: `open.spotify.com/embed/…`
+ * is the public embed player, and the page carries the track's metadata in a
+ * `__NEXT_DATA__` script tag. It needs no credentials, which is the whole
+ * point, but it is **not a documented API** — it is a page built for a browser,
+ * and Spotify can change its markup whenever it likes.
+ *
+ * So it is treated as a nicety, never a dependency: every failure answers an
+ * empty object, a lookup is skipped entirely when the ref already has what it
+ * needs, and a host that would rather not reach the network at all passes
+ * `lookup: null`. Nothing about whether a track *plays* runs through here.
+ *
+ * The `__NEXT_DATA__` walk and the cover-picking exist because the queue source
+ * returns ids with the names stripped out, and a queue showing raw URIs until
+ * each entry starts is useless for the one thing a queue is for.
+ */
+export type TrackLookup = (id: SpotifyId) => Promise<Partial<MediaRef>>;
+
+const EMPTY: Partial<MediaRef> = {};
+
+/**
+ * Facts resolved once, kept for the life of the process.
+ *
+ * A title is a property of the track, not of this lookup, and a poll-driven
+ * queue re-reads the same entries repeatedly. Caching by URI turns a settled
+ * queue into zero network calls after the first pass.
+ *
+ * Only non-empty results are cached: a failed lookup should retry on the next
+ * pass rather than freezing a track as nameless for the whole session.
+ */
+const cache = new Map<string, Partial<MediaRef>>();
+
+/** Everything the queue would want to show, from the public embed page. */
+export const embedLookup: TrackLookup = async (parsed) => {
+  const uri = toSpotifyUri(parsed);
+  const hit = cache.get(uri);
+  if (hit) return hit;
+
+  const facts = await fetchEmbed(parsed);
+  if (Object.keys(facts).length > 0) cache.set(uri, facts);
+  return facts;
+};
+
+/** Drop everything remembered. Exported for tests; a host has no reason to. */
+export function clearMetadataCache(): void {
+  cache.clear();
+}
+
+async function fetchEmbed(parsed: SpotifyId): Promise<Partial<MediaRef>> {
+  try {
+    const response = await fetch(
+      `https://open.spotify.com/embed/${parsed.kind}/${encodeURIComponent(parsed.id)}`,
+      // The page varies its markup for a bare client, so it is asked for the
+      // way a browser would ask.
+      { headers: { 'user-agent': 'Mozilla/5.0' } },
+    );
+    if (!response.ok) return EMPTY;
+    return readEmbedHtml(await response.text());
+  } catch {
+    // Offline, DNS, a redirect loop, a changed page — all the same answer. A
+    // track with no title still plays.
+    return EMPTY;
+  }
+}
+
+/**
+ * Split from the fetch and exported so the fragile half — the shape of a page
+ * we do not control — is covered by a test holding a real captured payload,
+ * with no network in it.
+ */
+export function readEmbedHtml(html: string): Partial<MediaRef> {
+  const match = html.match(
+    /<script id="__NEXT_DATA__" type="application\/json">(.*?)<\/script>/s,
+  );
+  if (!match?.[1]) return EMPTY;
+
+  let data: unknown;
+  try {
+    data = JSON.parse(match[1]);
+  } catch {
+    return EMPTY;
+  }
+
+  const entity = readPath(data, ['props', 'pageProps', 'state', 'data', 'entity']);
+  if (!entity || typeof entity !== 'object') return EMPTY;
+  const record = entity as Record<string, unknown>;
+
+  const out: Partial<MediaRef> = {};
+
+  const title = text(record.title) ?? text(record.name);
+  if (title) out.title = title;
+
+  const artist = Array.isArray(record.artists)
+    ? record.artists
+        .map((entry) =>
+          entry && typeof entry === 'object'
+            ? (text((entry as Record<string, unknown>).name) ?? '')
+            : '',
+        )
+        .filter(Boolean)
+        .join(', ')
+    : '';
+  if (artist) out.artist = artist;
+
+  const duration = record.duration;
+  if (typeof duration === 'number' && Number.isFinite(duration) && duration > 0) {
+    out.durationMs = Math.round(duration);
+  }
+
+  const visual =
+    record.visualIdentity && typeof record.visualIdentity === 'object'
+      ? (record.visualIdentity as Record<string, unknown>)
+      : {};
+  const artwork = pickCover(visual.image);
+  if (artwork) out.artwork = artwork;
+
+  return out;
+}
+
+/**
+ * The cover closest to the size a list actually draws: the smallest source at
+ * least 300px wide, or the largest on offer if none reach that.
+ */
+function pickCover(images: unknown): string | null {
+  if (!Array.isArray(images)) return null;
+  const sized: Array<{ url: string; width: number }> = [];
+  for (const image of images) {
+    if (!image || typeof image !== 'object') continue;
+    const record = image as Record<string, unknown>;
+    const url = typeof record.url === 'string' ? record.url : '';
+    if (!url.startsWith('https://')) continue;
+    const width = typeof record.maxWidth === 'number' ? record.maxWidth : 0;
+    sized.push({ url, width });
+  }
+  if (sized.length === 0) return null;
+
+  const enough = sized.filter((entry) => entry.width >= 300).sort((a, b) => a.width - b.width);
+  if (enough[0]) return enough[0].url;
+  return [...sized].sort((a, b) => b.width - a.width)[0]?.url ?? null;
+}
+
+/** Walk a chain of keys through untrusted JSON, stopping at the first step that
+ * is not an object rather than throwing. */
+function readPath(value: unknown, keys: string[]): unknown {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}

package/src/ref.ts

@@ -0,0 +1,145 @@
+import type { MediaRef } from 'upnext-core';
+
+/**
+ * Spotify's track JSON, read defensively into a `MediaRef`.
+ *
+ * Every field is checked rather than trusted. This is a network payload from a
+ * service that has changed its shapes before, and the difference between a
+ * missing field and a wrong one is the difference between a queue row with no
+ * cover and a `durationMs` of `NaN` — which the runtime would treat as a real
+ * duration and use to decide the track was over.
+ *
+ * The one field worth going out of the way for is `external_ids.isrc`. It is
+ * the recording-level id, and carrying it is what lets the same queue entry be
+ * found in someone else's Apple Music library, or fall back to a local file, or
+ * be handed to a completely different adapter when this one is unavailable. A
+ * Spotify URI identifies a row in Spotify's catalogue; an ISRC identifies the
+ * song.
+ */
+export function readTrack(value: unknown): MediaRef | null {
+  if (!value || typeof value !== 'object') return null;
+  const track = value as Record<string, unknown>;
+
+  const uri = text(track.uri);
+  const title = text(track.name);
+  if (!uri && !title) return null;
+
+  const ref: MediaRef = {};
+  if (title) ref.title = title;
+  if (uri) ref.uri = uri;
+
+  const artist = readArtists(track.artists);
+  if (artist) ref.artist = artist;
+
+  const album = track.album;
+  if (album && typeof album === 'object') {
+    const name = text((album as Record<string, unknown>).name);
+    if (name) ref.album = name;
+    const artwork = pickImage((album as Record<string, unknown>).images);
+    if (artwork) ref.artwork = artwork;
+  }
+
+  // A podcast episode has no album and no artists: its cover hangs off the
+  // episode itself and its "artist" is the show. Reading both here is what
+  // stops an episode from arriving in the queue as a bare URI.
+  if (!ref.artwork) {
+    const artwork = pickImage(track.images);
+    if (artwork) ref.artwork = artwork;
+  }
+  if (!ref.artist) {
+    const show = track.show;
+    if (show && typeof show === 'object') {
+      const name = text((show as Record<string, unknown>).name);
+      if (name) ref.artist = name;
+    }
+  }
+
+  const durationMs = track.duration_ms;
+  if (typeof durationMs === 'number' && Number.isFinite(durationMs) && durationMs > 0) {
+    ref.durationMs = Math.round(durationMs);
+  }
+
+  const isrc = readIsrc(track.external_ids);
+  if (isrc) ref.isrc = isrc;
+
+  return ref;
+}
+
+/**
+ * Artists as a comma-joined line.
+ *
+ * Handles both shapes on purpose. The Web API returns objects with a `name`;
+ * tools that normalise Spotify's payloads — spogo among them — flatten the same
+ * field to plain strings. Accepting either costs three lines and means this
+ * function is reusable by an out-of-process adapter that went through one of
+ * them.
+ */
+function readArtists(value: unknown): string | null {
+  if (!Array.isArray(value)) return null;
+  const names = value
+    .map((entry) => {
+      if (typeof entry === 'string') return entry.trim();
+      if (entry && typeof entry === 'object') {
+        return text((entry as Record<string, unknown>).name) ?? '';
+      }
+      return '';
+    })
+    .filter(Boolean);
+  return names.length > 0 ? names.join(', ') : null;
+}
+
+function readIsrc(value: unknown): string | null {
+  if (!value || typeof value !== 'object') return null;
+  const isrc = (value as Record<string, unknown>).isrc;
+  return typeof isrc === 'string' && /^[A-Za-z0-9]{12}$/.test(isrc.trim())
+    ? isrc.trim().toUpperCase()
+    : null;
+}
+
+/** The smallest cover at least 300px wide, or the largest on offer. */
+function pickImage(value: unknown): string | null {
+  if (!Array.isArray(value)) return null;
+  const sized: Array<{ url: string; width: number }> = [];
+  for (const image of value) {
+    if (!image || typeof image !== 'object') continue;
+    const record = image as Record<string, unknown>;
+    const url = text(record.url);
+    if (!url?.startsWith('https://')) continue;
+    sized.push({ url, width: typeof record.width === 'number' ? record.width : 0 });
+  }
+  if (sized.length === 0) return null;
+  const enough = sized.filter((entry) => entry.width >= 300).sort((a, b) => a.width - b.width);
+  return enough[0]?.url ?? [...sized].sort((a, b) => b.width - a.width)[0]?.url ?? null;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * A search query in Spotify's field syntax.
+ *
+ * Quoted fields rather than a bare concatenation, because "Bad Habit Steve
+ * Lacy" as free text returns covers and remixes above the original often
+ * enough to matter, and the runtime is going to score whatever comes back
+ * against what was asked for and reject it if it does not match closely enough.
+ * A tighter query means fewer of those rejections.
+ */
+export function searchQuery(ref: MediaRef): string | null {
+  if (ref.isrc) return `isrc:${ref.isrc}`;
+  const parts: string[] = [];
+  if (ref.title) parts.push(`track:"${escapeQuery(ref.title)}"`);
+  if (ref.artist) parts.push(`artist:"${escapeQuery(primary(ref.artist))}"`);
+  if (ref.album && !ref.artist) parts.push(`album:"${escapeQuery(ref.album)}"`);
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
+/** Only the first credited artist: a featuring credit spelled differently on
+ * two services turns an exact-match query into a miss. */
+function primary(artist: string): string {
+  return artist.split(/,| feat\.? | ft\.? | & /i)[0]?.trim() || artist;
+}
+
+function escapeQuery(value: string): string {
+  return value.replace(/["\\]/g, ' ').replace(/\s+/g, ' ').trim();
+}