upnext-adapter-spotify 0.1.0

package/src/sampler.ts

@@ -0,0 +1,173 @@
+import type { AdapterEvent } from 'upnext-core';
+import type { Sample } from './applescript.js';
+
+/**
+ * Deciding what two consecutive readings of the Spotify app *mean*.
+ *
+ * This is the only genuinely hard code in the package, and it exists because of
+ * one ambiguity the core cannot resolve on its own: **the track we loaded is no
+ * longer the track that is playing.** That single observation has two completely
+ * opposite causes.
+ *
+ *   Our track finished and Spotify's own queue rolled to the next thing.
+ *     → the queue should advance to *our* next entry. This is `ended`.
+ *
+ *   A person picked up their phone and hit next, or clicked a different album.
+ *     → the human wins. This is `external`, and the reconciler adopts it.
+ *
+ * Get it backwards and the library is broken in the most visible possible way:
+ * either an agent's carefully built queue silently defers to Spotify's autoplay
+ * after every single song, or a listener who chooses a song has it yanked away.
+ *
+ * What separates them is *where the playhead was on the previous reading*. A
+ * rollover can only happen at the end of a track, so a change of track that
+ * follows a sample near the end is a rollover, and a change that follows a
+ * sample in the middle is a person. The core cannot make that call, because by
+ * the time it sees the mismatch the evidence — the previous position — is gone.
+ * The adapter can, because it kept it. This is exactly the kind of knowledge the
+ * adapter contract exists to keep on the adapter's side.
+ *
+ * All of it is pure, and none of it needs a Mac. The state goes in and comes
+ * back out, so every branch below is a plain table-driven test rather than
+ * something you have to install Spotify and wait three minutes to observe.
+ */
+
+export interface WatchState {
+  /** The previous reading, or null before the first one. */
+  last: Sample | null;
+  /** Have we ever seen Spotify actually playing the track we asked for? */
+  confirmed: boolean;
+  /** Readings taken since the load without that confirmation. */
+  attempts: number;
+  /** Whether the "it never started" complaint has already been made. */
+  complained: boolean;
+}
+
+export const initialWatchState: WatchState = {
+  last: null,
+  confirmed: false,
+  attempts: 0,
+  complained: false,
+};
+
+export interface InterpretOptions {
+  /**
+   * How close to the end of a track counts as "at the end".
+   *
+   * Must be at least a couple of sampling intervals: the last reading before a
+   * rollover can be a whole interval short of the duration, and if the window
+   * is tighter than that, every natural track change is misread as a human
+   * taking over. Erring wide is the safer direction — the cost of a window that
+   * is slightly too generous is that a person who skips in the final seconds of
+   * a song gets the same outcome they were going to get anyway.
+   */
+  rolloverWindowMs: number;
+  /**
+   * How many readings to wait for `play track` to take effect before saying it
+   * did not. Spotify can take a moment to load a track, and until it has, the
+   * app is still reporting whatever it was playing before.
+   */
+  confirmWithin: number;
+}
+
+export interface Interpretation {
+  events: AdapterEvent[];
+  state: WatchState;
+}
+
+export function interpret(
+  ourUri: string,
+  state: WatchState,
+  next: Sample,
+  opts: InterpretOptions,
+): Interpretation {
+  const events: AdapterEvent[] = [];
+  const wasAtEnd = nearEnd(state.last, ourUri, opts.rolloverWindowMs);
+
+  // -- the app is not open --------------------------------------------------
+  if (!next.running) {
+    // Quitting Spotify in the last seconds of a song is still that song being
+    // over. Anywhere else it is the backend going away underneath us, which is
+    // reported as paused because that is what a listener would say is true:
+    // nothing is coming out of the speakers, and nothing is broken enough to
+    // fail the entry over.
+    if (wasAtEnd) return { events: [{ type: 'ended' }], state: { ...state, last: next } };
+    if (state.last?.running !== false) events.push({ type: 'status', status: 'paused' });
+    return { events, state: { ...state, last: next } };
+  }
+
+  // -- our track has not started yet ----------------------------------------
+  if (!state.confirmed) {
+    if (next.nativeUri !== ourUri) {
+      const attempts = state.attempts + 1;
+      // Whatever the app is still showing is the *previous* track, not a human
+      // choosing something. Reporting it as a takeover here would let the track
+      // we are in the middle of starting hijack its own start.
+      if (attempts >= opts.confirmWithin && !state.complained) {
+        events.push({
+          type: 'error',
+          code: 'not_playing',
+          message: `Spotify did not start ${ourUri}; it is playing ${next.nativeUri ?? 'nothing'}`,
+        });
+        return { events, state: { ...state, last: next, attempts, complained: true } };
+      }
+      return { events, state: { ...state, last: next, attempts } };
+    }
+    return {
+      events: report(state.last, next),
+      state: { ...state, last: next, confirmed: true },
+    };
+  }
+
+  // -- something else is playing --------------------------------------------
+  if (next.nativeUri !== ourUri) {
+    if (wasAtEnd) return { events: [{ type: 'ended' }], state: { ...state, last: next } };
+    if (next.nativeUri === null) {
+      // Spotify is open with nothing loaded. `external` carrying null is a
+      // no-op to the reconciler by design — "reporting nothing" is not the same
+      // as "reporting a different song" — so the honest signal is that playback
+      // stopped.
+      if (state.last?.nativeUri !== null) events.push({ type: 'status', status: 'paused' });
+      return { events, state: { ...state, last: next } };
+    }
+    return {
+      events: [{ type: 'external', nativeUri: next.nativeUri }],
+      state: { ...state, last: next },
+    };
+  }
+
+  // -- still our track ------------------------------------------------------
+  // Spotify with no autoplay behind it parks at the end of the last track
+  // rather than announcing anything, so a track that is at its end and no
+  // longer playing is a track that is over. Without this the queue would sit
+  // there, holding a finished song, waiting for a change that never comes.
+  if (next.status !== 'playing' && atEnd(next, opts.rolloverWindowMs)) {
+    return { events: [{ type: 'ended' }], state: { ...state, last: next } };
+  }
+
+  return { events: report(state.last, next), state: { ...state, last: next } };
+}
+
+/** Position every time, status only when it actually changed. */
+function report(last: Sample | null, next: Sample): AdapterEvent[] {
+  const events: AdapterEvent[] = [
+    next.durationMs
+      ? { type: 'position', positionMs: next.positionMs, durationMs: next.durationMs }
+      : { type: 'position', positionMs: next.positionMs },
+  ];
+  if (last?.status !== next.status) {
+    events.push({ type: 'status', status: next.status === 'idle' ? 'paused' : next.status });
+  }
+  return events;
+}
+
+/** Was the previous reading our track, at the end of it? */
+function nearEnd(last: Sample | null, ourUri: string, windowMs: number): boolean {
+  if (!last || !last.running || last.nativeUri !== ourUri) return false;
+  return atEnd(last, windowMs);
+}
+
+function atEnd(sample: Sample, windowMs: number): boolean {
+  if (sample.durationMs === null) return false;
+  return sample.positionMs >= sample.durationMs - windowMs;
+}

package/src/uri.ts

@@ -0,0 +1,104 @@
+/**
+ * Reading Spotify's two ways of naming the same thing.
+ *
+ * A ref can arrive carrying either form — `spotify:track:6f3Slt0GbA2bPZlz0aIFXN`
+ * from an API, or `https://open.spotify.com/track/6f3Slt0GbA2bPZlz0aIFXN?si=…`
+ * from a person pasting a share link — and both adapters have to treat them as
+ * the same track. Everything downstream works in the `spotify:` form, because
+ * that is what the AppleScript dictionary and the Web API both accept.
+ *
+ * Parsing is total: anything unrecognised answers `null` rather than throwing,
+ * so `match` can score a ref without a try/catch around it.
+ */
+
+export type SpotifyKind = 'track' | 'episode' | 'album' | 'playlist' | 'artist' | 'show';
+
+export interface SpotifyId {
+  kind: SpotifyKind;
+  /** The base-62 id, without any prefix. */
+  id: string;
+}
+
+const KINDS = new Set<string>(['track', 'episode', 'album', 'playlist', 'artist', 'show']);
+
+/**
+ * Kinds that name one playable item.
+ *
+ * The rest are *containers*, and a container is not a queue entry — this
+ * library's whole shape is one item at a time, with the ordering owned above
+ * the backend. An album URI is a request to enqueue many things, which is
+ * `expandContext` plus `enqueueMany`, not a single bind.
+ */
+export function isPlayableKind(kind: SpotifyKind): boolean {
+  return kind === 'track' || kind === 'episode';
+}
+
+/** Spotify ids are base-62. Length is not pinned: it is 22 today, and a format
+ * check that is wrong in two years is worse than one that is slightly loose. */
+const ID = /^[A-Za-z0-9]{8,64}$/;
+
+export function parseSpotifyUri(value: string | undefined | null): SpotifyId | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.toLowerCase().startsWith('spotify:')
+    ? fromUri(trimmed)
+    : fromUrl(trimmed);
+}
+
+/**
+ * `spotify:track:ID`, and the legacy `spotify:user:someone:playlist:ID`.
+ *
+ * Scanning from the right rather than reading position 1 is what handles the
+ * legacy form, and it costs nothing on the common one. `spotify:local:…` has no
+ * base-62 id at all and falls out on its own — which is correct, since a local
+ * file in someone's Spotify library is not something either backend can locate.
+ */
+function fromUri(value: string): SpotifyId | null {
+  const parts = value.split(':');
+  for (let i = parts.length - 2; i >= 0; i--) {
+    const kind = parts[i]?.toLowerCase();
+    const id = parts[i + 1];
+    if (kind && KINDS.has(kind) && id && ID.test(id)) {
+      return { kind: kind as SpotifyKind, id };
+    }
+  }
+  return null;
+}
+
+/**
+ * `https://open.spotify.com/track/ID`, with or without a locale segment.
+ *
+ * The locale form (`/intl-de/track/ID`) is what the mobile app produces when
+ * someone shares from a non-English device, so it is not an edge case — it is
+ * half of the share links a person will actually paste. Scanning the path for a
+ * known kind absorbs it, and the legacy `play.spotify.com` host, without a
+ * pattern per variant.
+ */
+function fromUrl(value: string): SpotifyId | null {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (!/(^|\.)spotify\.com$/i.test(url.hostname)) return null;
+
+  const segments = url.pathname.split('/').filter(Boolean);
+  for (let i = 0; i < segments.length - 1; i++) {
+    const kind = segments[i]?.toLowerCase();
+    const id = segments[i + 1];
+    if (kind && KINDS.has(kind) && id && ID.test(id)) {
+      return { kind: kind as SpotifyKind, id };
+    }
+  }
+  return null;
+}
+
+export function toSpotifyUri(parsed: SpotifyId): string {
+  return `spotify:${parsed.kind}:${parsed.id}`;
+}
+
+export function toSpotifyUrl(parsed: SpotifyId): string {
+  return `https://open.spotify.com/${parsed.kind}/${parsed.id}`;
+}

package/src/watch.ts

@@ -0,0 +1,145 @@
+import type { Scheduler } from 'upnext-core';
+import type { AdapterEvent } from 'upnext-core';
+import type { Sample } from './applescript.js';
+import { SpotifyError } from './errors.js';
+import { initialWatchState, interpret, type WatchState } from './sampler.js';
+
+export interface BackendWatcherDeps {
+  /** Take one reading. `null` means the reading was unusable, not that it failed. */
+  read(): Promise<Sample | null>;
+  emit(event: AdapterEvent): void;
+  scheduler: Scheduler;
+  intervalMs: number;
+  rolloverWindowMs: number;
+  confirmWithin: number;
+}
+
+/**
+ * The loop that turns readings into events, shared by both backends.
+ *
+ * Extracted because the desktop app and the Web API differ only in how a
+ * reading is *taken* — one shells out to `osascript`, the other makes an HTTP
+ * call — and are identical in what happens around it: do not let a slow read
+ * stack up behind itself, do not report the same outage once a second, decide
+ * what changed, and stop the moment a track ends so nothing ends twice.
+ *
+ * Keeping one copy is not only tidier, it is safer. The re-targeting below is
+ * subtle enough that having it in two places would mean having it wrong in one.
+ */
+export class BackendWatcher {
+  #deps: BackendWatcherDeps;
+  #target: string | null = null;
+  #state: WatchState = initialWatchState;
+  #timer: unknown = null;
+  #reading = false;
+  #failing = false;
+
+  constructor(deps: BackendWatcherDeps) {
+    this.#deps = deps;
+  }
+
+  /** What this watcher currently believes it is following. */
+  get target(): string | null {
+    return this.#target;
+  }
+
+  start(nativeUri: string): void {
+    this.#target = nativeUri;
+    this.#state = initialWatchState;
+    this.#failing = false;
+    if (this.#timer !== null) return;
+    this.#timer = this.#deps.scheduler.setInterval(() => {
+      void this.tick();
+    }, this.#deps.intervalMs);
+  }
+
+  stop(): void {
+    this.#target = null;
+    this.#state = initialWatchState;
+    if (this.#timer === null) return;
+    this.#deps.scheduler.clearInterval(this.#timer);
+    this.#timer = null;
+    this.#reading = false;
+  }
+
+  /** One pass. Exposed so a test can step it without a scheduler. */
+  async tick(): Promise<void> {
+    // A slow read must not let ticks pile up behind it. Skipping is the right
+    // response rather than queueing: the next reading supersedes this one, so a
+    // dropped pass costs a second of resolution and nothing else.
+    if (this.#reading) return;
+    const target = this.#target;
+    if (target === null) return;
+
+    this.#reading = true;
+    let sample: Sample | null;
+    try {
+      sample = await this.#deps.read();
+      this.#failing = false;
+    } catch (err) {
+      this.#report(err);
+      return;
+    } finally {
+      this.#reading = false;
+    }
+
+    // The world moved while we were awaiting: something else is loaded now and
+    // this reading describes the track before it.
+    if (this.#target !== target || !sample) return;
+
+    const { events, state } = interpret(target, this.#state, sample, {
+      rolloverWindowMs: this.#deps.rolloverWindowMs,
+      confirmWithin: this.#deps.confirmWithin,
+    });
+    this.#state = state;
+
+    /**
+     * Follow the backend when a person moves it.
+     *
+     * Without this the watcher would go on comparing every reading against the
+     * track the listener already abandoned, announce a takeover again a second
+     * later, and again after that — and since the runtime's default is to adopt
+     * what the human chose, each one would add another entry to the queue. A
+     * takeover is one piece of news; after it, this *is* the track we are on.
+     *
+     * Whichever way the runtime rules, this ends up correct: on `adopt` the
+     * runtime never calls `load` again, so re-targeting here is the only thing
+     * that keeps the two in step; on `correct` it calls `load` and `play`,
+     * which resets this watcher outright; on `ignore` following along is
+     * precisely what ignoring means.
+     */
+    const takeover = events.find((event) => event.type === 'external');
+    if (takeover?.type === 'external' && takeover.nativeUri) {
+      this.#target = takeover.nativeUri;
+      this.#state = { last: sample, confirmed: true, attempts: 0, complained: false };
+    }
+
+    // Stop before announcing. The runtime tears this down on its way to the
+    // next entry, but not before the timer could have fired again, and one
+    // track must never end twice.
+    if (events.some((event) => event.type === 'ended')) this.stop();
+    for (const event of events) this.#deps.emit(event);
+  }
+
+  /**
+   * Say an outage happened once, not once per tick.
+   *
+   * A machine that has just declined Automation permission, or a token that has
+   * stopped working, would otherwise emit an identical error every interval for
+   * as long as the queue is open. A rate limit additionally stops the loop: the
+   * watcher is the only thing here that runs unasked, so it is the only thing
+   * that can dig the hole deeper on its own.
+   */
+  #report(err: unknown): void {
+    this.#reading = false;
+    if (!this.#failing) {
+      this.#failing = true;
+      this.#deps.emit({
+        type: 'error',
+        code: err instanceof SpotifyError ? err.reason : 'sample_failed',
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+    if (err instanceof SpotifyError && err.reason === 'rate-limited') this.stop();
+  }
+}