upnext-adapter-spotify 0.1.0

package/dist/src/ref.js

@@ -0,0 +1,150 @@
+/**
+ * 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) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const track = value;
+    const uri = text(track.uri);
+    const title = text(track.name);
+    if (!uri && !title)
+        return null;
+    const ref = {};
+    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.name);
+        if (name)
+            ref.album = name;
+        const artwork = pickImage(album.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.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) {
+    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.name) ?? '';
+        }
+        return '';
+    })
+        .filter(Boolean);
+    return names.length > 0 ? names.join(', ') : null;
+}
+function readIsrc(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const isrc = value.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) {
+    if (!Array.isArray(value))
+        return null;
+    const sized = [];
+    for (const image of value) {
+        if (!image || typeof image !== 'object')
+            continue;
+        const record = image;
+        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) {
+    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) {
+    if (ref.isrc)
+        return `isrc:${ref.isrc}`;
+    const parts = [];
+    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) {
+    return artist.split(/,| feat\.? | ft\.? | & /i)[0]?.trim() || artist;
+}
+function escapeQuery(value) {
+    return value.replace(/["\\]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+//# sourceMappingURL=ref.js.map

package/dist/src/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../src/ref.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,KAAgC,CAAC;IAE/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAEhC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAC7B,IAAI,GAAG;QAAE,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC;IAEvB,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,MAAM;QAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;IAEhC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAE,KAAiC,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,IAAI;YAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;QAC3B,MAAM,OAAO,GAAG,SAAS,CAAE,KAAiC,CAAC,MAAM,CAAC,CAAC;QACrE,IAAI,OAAO;YAAE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACrC,CAAC;IAED,yEAAyE;IACzE,yEAAyE;IACzE,6DAA6D;IAC7D,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,OAAO;YAAE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,IAAI,CAAE,IAAgC,CAAC,IAAI,CAAC,CAAC;YAC1D,IAAI,IAAI;gBAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC;IACrC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACpF,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1C,IAAI,IAAI;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAE1B,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,KAAK,GAAG,KAAK;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,IAAI,CAAE,KAAiC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7D,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;SACD,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,IAAI,GAAI,KAAiC,CAAC,IAAI,CAAC;IACrD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACtE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;QAC3B,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,uEAAuE;AACvE,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,KAAK,GAA0C,EAAE,CAAC;IACxD,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QAClD,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC;YAAE,SAAS;QAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC7F,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC;AACxF,CAAC;AAED,SAAS,IAAI,CAAC,KAAc;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACzE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,IAAI,GAAG,CAAC,IAAI;QAAE,OAAO,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/D,IAAI,GAAG,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3E,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED;0DAC0D;AAC1D,SAAS,OAAO,CAAC,MAAc;IAC7B,OAAO,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,MAAM,CAAC;AACvE,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC"}

package/dist/src/sampler.d.ts

@@ -0,0 +1,68 @@
+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 declare const initialWatchState: WatchState;
+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 declare function interpret(ourUri: string, state: WatchState, next: Sample, opts: InterpretOptions): Interpretation;
+//# sourceMappingURL=sampler.d.ts.map

package/dist/src/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../src/sampler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB,EAAE,UAK/B,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,cAAc,CAkEhB"}

package/dist/src/sampler.js

@@ -0,0 +1,96 @@
+export const initialWatchState = {
+    last: null,
+    confirmed: false,
+    attempts: 0,
+    complained: false,
+};
+export function interpret(ourUri, state, next, opts) {
+    const events = [];
+    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, next) {
+    const events = [
+        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, ourUri, windowMs) {
+    if (!last || !last.running || last.nativeUri !== ourUri)
+        return false;
+    return atEnd(last, windowMs);
+}
+function atEnd(sample, windowMs) {
+    if (sample.durationMs === null)
+        return false;
+    return sample.positionMs >= sample.durationMs - windowMs;
+}
+//# sourceMappingURL=sampler.js.map

package/dist/src/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../../src/sampler.ts"],"names":[],"mappings":"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"}

package/dist/src/uri.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function isPlayableKind(kind: SpotifyKind): boolean;
+export declare function parseSpotifyUri(value: string | undefined | null): SpotifyId | null;
+export declare function toSpotifyUri(parsed: SpotifyId): string;
+export declare function toSpotifyUrl(parsed: SpotifyId): string;
+//# sourceMappingURL=uri.d.ts.map

package/dist/src/uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.d.ts","sourceRoot":"","sources":["../../src/uri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;CACZ;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEzD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAOlF;AAmDD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEtD"}

package/dist/src/uri.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+const KINDS = new Set(['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) {
+    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) {
+    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) {
+    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, 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) {
+    let 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, id };
+        }
+    }
+    return null;
+}
+export function toSpotifyUri(parsed) {
+    return `spotify:${parsed.kind}:${parsed.id}`;
+}
+export function toSpotifyUrl(parsed) {
+    return `https://open.spotify.com/${parsed.kind}/${parsed.id}`;
+}
+//# sourceMappingURL=uri.js.map

package/dist/src/uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.js","sourceRoot":"","sources":["../../src/uri.ts"],"names":[],"mappings":"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"}

package/dist/src/watch.d.ts

@@ -0,0 +1,35 @@
+import type { Scheduler } from 'upnext-core';
+import type { AdapterEvent } from 'upnext-core';
+import type { Sample } from './applescript.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 declare class BackendWatcher {
+    #private;
+    constructor(deps: BackendWatcherDeps);
+    /** What this watcher currently believes it is following. */
+    get target(): string | null;
+    start(nativeUri: string): void;
+    stop(): void;
+    /** One pass. Exposed so a test can step it without a scheduler. */
+    tick(): Promise<void>;
+}
+//# sourceMappingURL=watch.d.ts.map

package/dist/src/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/watch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI/C,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;;gBAQb,IAAI,EAAE,kBAAkB;IAIpC,4DAA4D;IAC5D,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAU9B,IAAI,IAAI,IAAI;IASZ,mEAAmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA+E5B"}

package/dist/src/watch.js

@@ -0,0 +1,131 @@
+import { SpotifyError } from './errors.js';
+import { initialWatchState, interpret } from './sampler.js';
+/**
+ * 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;
+    #target = null;
+    #state = initialWatchState;
+    #timer = null;
+    #reading = false;
+    #failing = false;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /** What this watcher currently believes it is following. */
+    get target() {
+        return this.#target;
+    }
+    start(nativeUri) {
+        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() {
+        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() {
+        // 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;
+        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) {
+        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();
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/src/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/watch.ts"],"names":[],"mappings":"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"}