upnext-adapter-spotify 0.1.0

package/dist/src/applescript.js

@@ -0,0 +1,197 @@
+import { execFile } from 'node:child_process';
+import { SpotifyError, classifyText } from './errors.js';
+import { parseSpotifyUri, toSpotifyUri } from './uri.js';
+/**
+ * Talking to the Spotify desktop app through its AppleScript dictionary.
+ *
+ * The script text and the parsing are separated on purpose, and both are
+ * exported. AppleScript is a string until the moment it runs, so the part most
+ * likely to break — a field order that drifts, a property spelled wrong — is
+ * exactly the part a type checker cannot see. Keeping the parser pure means the
+ * wire format has real tests on a machine with no Spotify, no macOS and no
+ * network, which is where this package's CI runs.
+ */
+/** ASCII unit separator. Written as an escape because the character is
+ * invisible in an editor, and chosen over a tab or a pipe because a track title
+ * is free text — anything a person might plausibly type would split a title in
+ * half. */
+export const FIELD = '\u001F';
+/** How long any one script may take. A beachballing player, or a first run
+ * waiting on the macOS Automation consent prompt, must not hold a sample
+ * forever and let the next one stack behind it. */
+export const SCRIPT_TIMEOUT_MS = 5_000;
+export function runOsascript(script) {
+    return new Promise((resolve, reject) => {
+        execFile('osascript', ['-e', script], { timeout: SCRIPT_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (!error)
+                return resolve(stdout);
+            const text = String(stderr || error.message);
+            if (error.code === 'ENOENT') {
+                return reject(new SpotifyError('unavailable', 'osascript is not available on this system'));
+            }
+            reject(new SpotifyError(classifyText(text), text.trim() || 'osascript failed'));
+        });
+    });
+}
+/**
+ * Read the app's state without ever launching it.
+ *
+ * `if application "Spotify" is running` is the load-bearing line. A bare
+ * `tell application "Spotify"` *launches* Spotify, so a sampler running every
+ * second would boot a music player onto the machine of someone who never opened
+ * one — and would do it on a poll the user never asked for. The guard is what
+ * makes this safe to run on a timer.
+ *
+ * Every property sits behind its own `try` so that one that errors — and
+ * `current track` errors whenever nothing is loaded — costs its own field
+ * rather than the whole reading.
+ */
+export function stateScript() {
+    return `on run
+	set AppleScript's text item delimiters to (ASCII character 31)
+	if application "Spotify" is running then
+		tell application "Spotify"
+			set stateField to "idle"
+			set positionField to "0"
+			set trackField to ""
+			set durationField to ""
+			set volumeField to ""
+			try
+				set stateField to (player state as text)
+			end try
+			try
+				set positionField to (player position as text)
+			end try
+			try
+				set trackField to (id of current track as text)
+			end try
+			try
+				set durationField to (duration of current track as text)
+			end try
+			try
+				set volumeField to (sound volume as text)
+			end try
+			return {"running", stateField, positionField, trackField, durationField, volumeField} as text
+		end tell
+	end if
+	return ""
+end run`;
+}
+/**
+ * Turn a reading into a `Sample`, or `null` if the text is not one.
+ *
+ * Anything malformed answers null rather than a half-filled sample: a sample
+ * with a NaN playhead would be read as a real position and could end a track
+ * that is still playing, where a missing sample simply means this tick learned
+ * nothing and the next one will.
+ */
+export function parseSample(raw) {
+    const trimmed = raw.trim();
+    // Empty is the script's own word for "Spotify is not open" — a real answer.
+    if (!trimmed) {
+        return { running: false, status: 'idle', positionMs: 0, durationMs: null, nativeUri: null, volume: null };
+    }
+    const fields = trimmed.split(FIELD);
+    if (fields[0] !== 'running' || fields.length < 6)
+        return null;
+    const parsed = parseSpotifyUri(fields[3]);
+    const durationMs = positiveInt(fields[4]);
+    const volume = positiveFloat(fields[5]);
+    return {
+        running: true,
+        status: readStatus(fields[1]),
+        // Spotify reports the playhead in seconds and the track length in
+        // milliseconds. Everything above this line is milliseconds.
+        positionMs: Math.round((positiveFloat(fields[2]) ?? 0) * 1000),
+        durationMs,
+        nativeUri: parsed ? toSpotifyUri(parsed) : null,
+        volume: volume === null ? null : Math.min(1, Math.max(0, volume / 100)),
+    };
+}
+/** Spotify's dictionary spells the three states exactly this way. */
+function readStatus(value) {
+    if (value === 'playing')
+        return 'playing';
+    if (value === 'paused')
+        return 'paused';
+    return 'idle';
+}
+function positiveFloat(value) {
+    const parsed = Number.parseFloat(value ?? '');
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+function positiveInt(value) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+// -- commands ---------------------------------------------------------------
+/**
+ * Start a specific track.
+ *
+ * This is the one script allowed to launch Spotify, because it only ever runs
+ * as the direct result of something asking for playback. `activate` is
+ * deliberately absent: starting a song should not take the foreground away from
+ * whatever the person is actually looking at.
+ *
+ * A start offset needs the pause. `play track` returns as soon as the command
+ * is accepted, not when the track is loaded, and moving the playhead of a track
+ * that has not loaded yet either errors or is silently discarded — so the seek
+ * is retried until it takes, which costs nothing in the common case where
+ * `startAtMs` is zero and none of this runs.
+ */
+export function playTrackScript(nativeUri, startAtMs = 0) {
+    const seconds = Math.max(0, Math.round(startAtMs / 1000));
+    const seek = seconds > 0
+        ? `
+		repeat 20 times
+			try
+				if player state is playing then
+					set player position to ${seconds}
+					exit repeat
+				end if
+			end try
+			delay 0.1
+		end repeat`
+        : '';
+    return `tell application "Spotify"
+		play track ${quote(nativeUri)}${seek}
+	end tell`;
+}
+/**
+ * Any other verb, wrapped so it cannot launch the app.
+ *
+ * There is nothing to pause, seek or re-level in an app that is not open, and
+ * launching one to tell it to be quiet would be absurd — so unlike
+ * `playTrackScript`, everything here is behind the running guard.
+ */
+export function commandScript(body) {
+    return `if application "Spotify" is running then
+	tell application "Spotify"
+		${body}
+	end tell
+end if`;
+}
+export const commands = {
+    play: 'play',
+    /**
+     * Spotify's dictionary has no stop that does not quit the app, and quitting
+     * someone's music player because a queue moved to a different source would be
+     * far ruder than leaving it paused. `stop` therefore means pause here, and
+     * that is the honest description of what happens.
+     */
+    pause: 'pause',
+    seek: (positionMs) => `set player position to ${Math.max(0, Math.round(positionMs / 1000))}`,
+    volume: (volume) => `set sound volume to ${Math.min(100, Math.max(0, Math.round(volume * 100)))}`,
+};
+/**
+ * A string literal AppleScript will read as one string.
+ *
+ * Only ever given a `spotify:` URI built by `toSpotifyUri` from a validated
+ * base-62 id, so there is nothing here to escape in practice — but this text
+ * becomes a program, and a quoting function that exists is cheaper than the
+ * argument about whether the caller can always be trusted.
+ */
+function quote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+//# sourceMappingURL=applescript.js.map

package/dist/src/applescript.js.map

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

package/dist/src/desktop.d.ts

@@ -0,0 +1,100 @@
+import { type Scheduler } from 'upnext-core';
+import type { Adapter, AdapterEvent, Binding, Capabilities, MediaRef } from 'upnext-core';
+import { type Osascript } from './applescript.js';
+import { type TrackLookup } from './metadata.js';
+export interface SpotifyDesktopOptions {
+    id?: string;
+    /**
+     * How often to read the app while something is loaded.
+     *
+     * This is the resolution of every time-dependent thing the backend can tell
+     * us — the playhead, a pause someone made in the app, the end of a track.
+     * A second is comfortably below what a person notices and cheap enough to
+     * run for hours; the cost of each sample is one short-lived `osascript`.
+     */
+    sampleIntervalMs?: number;
+    /** Injected so the whole adapter is testable off macOS. */
+    osascript?: Osascript;
+    scheduler?: Scheduler;
+    /**
+     * How a bare Spotify URI becomes a title and a cover. `null` turns it off and
+     * the queue simply shows URIs — nothing about playback depends on it.
+     */
+    lookup?: TrackLookup | null;
+    /** Overridden only by tests; a real host is on whatever it is on. */
+    platform?: string;
+}
+/**
+ * Drives the Spotify desktop app on macOS, with no credentials at all.
+ *
+ * There is no OAuth here, no client id, no Premium check and nothing to
+ * register: it talks to the copy of Spotify already running on the machine
+ * through the AppleScript dictionary that ships with it. If someone can play
+ * music in Spotify, this can play music in Spotify.
+ *
+ * It is also the first backend in this project that a **human can fight**, and
+ * that is the interesting part. A local file is ours alone; the Spotify app has
+ * its own transport bar, its own queue, and a person holding a phone who is
+ * fully entitled to press next. So it declares `externalControl: true`, keeps
+ * enough history to tell a natural track change from a deliberate one (see
+ * `sampler.ts`), and lets the runtime's reconciler decide who wins — which by
+ * default is the person.
+ *
+ * What it deliberately does *not* claim:
+ *
+ *   `search: false` — the dictionary cannot search the catalogue. It could be
+ *     faked by scraping something, and then every `resolve` of a title would be
+ *     a guess dressed as a lookup. An adapter that says it cannot do a thing is
+ *     correct and slightly limited; one that says it can and then does it badly
+ *     is broken. Use `SpotifyWebAdapter` when you need search.
+ *
+ *   No `poll()` — `position: 'authoritative'` would normally make the runtime's
+ *     watcher poll this adapter on an interval. It samples itself instead,
+ *     because only the adapter can compare a reading against the one before it,
+ *     and that comparison is the whole rollover-versus-takeover decision.
+ *     Offering `poll` as well would mean two timers reading the same app.
+ */
+export declare class SpotifyDesktopAdapter implements Adapter {
+    #private;
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    constructor(options?: SpotifyDesktopOptions);
+    /**
+     * Fail here rather than at the first song.
+     *
+     * A backend whose `init` throws is excluded from selection and shows up in
+     * `getState().adapters` as `available: false` with the reason — so a host on
+     * Linux gets one clear "this backend is macOS-only" at startup instead of an
+     * agent discovering it one failed track at a time.
+     *
+     * `id of application "Spotify"` resolves the app through LaunchServices
+     * *without launching it*, which is the only way to ask "is Spotify even
+     * installed" that does not open a music player on someone's desktop.
+     */
+    init(): Promise<void>;
+    /**
+     * Only things that already name a Spotify track.
+     *
+     * Without search there is no way to get from "Bad Habit by Steve Lacy" to a
+     * URI, so scoring anything else above zero would win the ref away from an
+     * adapter that could actually have played it.
+     */
+    match(ref: MediaRef): number;
+    resolve(ref: MediaRef): Promise<Binding | null>;
+    load(binding: Binding, opts?: {
+        startAtMs?: number;
+    }): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    /**
+     * Spotify's dictionary has no stop that does not quit the app, so this
+     * pauses. Quitting somebody's music player because the queue moved on to a
+     * podcast would be a much bigger thing to do than the runtime is asking for.
+     */
+    stop(): Promise<void>;
+    seek(positionMs: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    subscribe(listener: (event: AdapterEvent) => void): () => void;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=desktop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../../src/desktop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAI9D,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,qBAAsB,YAAW,OAAO;;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CASjC;gBAaU,OAAO,GAAE,qBAA0B;IAoB/C;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IAKtB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAyB/C,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAa/B"}

package/dist/src/desktop.js

@@ -0,0 +1,194 @@
+import { defaultCapabilities, systemScheduler } from 'upnext-core';
+import { commandScript, commands, parseSample, playTrackScript, runOsascript, stateScript, } from './applescript.js';
+import { SpotifyError } from './errors.js';
+import { embedLookup } from './metadata.js';
+import { isPlayableKind, parseSpotifyUri, toSpotifyUri } from './uri.js';
+import { BackendWatcher } from './watch.js';
+/**
+ * Drives the Spotify desktop app on macOS, with no credentials at all.
+ *
+ * There is no OAuth here, no client id, no Premium check and nothing to
+ * register: it talks to the copy of Spotify already running on the machine
+ * through the AppleScript dictionary that ships with it. If someone can play
+ * music in Spotify, this can play music in Spotify.
+ *
+ * It is also the first backend in this project that a **human can fight**, and
+ * that is the interesting part. A local file is ours alone; the Spotify app has
+ * its own transport bar, its own queue, and a person holding a phone who is
+ * fully entitled to press next. So it declares `externalControl: true`, keeps
+ * enough history to tell a natural track change from a deliberate one (see
+ * `sampler.ts`), and lets the runtime's reconciler decide who wins — which by
+ * default is the person.
+ *
+ * What it deliberately does *not* claim:
+ *
+ *   `search: false` — the dictionary cannot search the catalogue. It could be
+ *     faked by scraping something, and then every `resolve` of a title would be
+ *     a guess dressed as a lookup. An adapter that says it cannot do a thing is
+ *     correct and slightly limited; one that says it can and then does it badly
+ *     is broken. Use `SpotifyWebAdapter` when you need search.
+ *
+ *   No `poll()` — `position: 'authoritative'` would normally make the runtime's
+ *     watcher poll this adapter on an interval. It samples itself instead,
+ *     because only the adapter can compare a reading against the one before it,
+ *     and that comparison is the whole rollover-versus-takeover decision.
+ *     Offering `poll` as well would mean two timers reading the same app.
+ */
+export class SpotifyDesktopAdapter {
+    id;
+    capabilities = {
+        ...defaultCapabilities,
+        endOfTrack: 'event',
+        position: 'authoritative',
+        externalControl: true,
+        seek: true,
+        pause: true,
+        volume: true,
+        search: false,
+    };
+    #osascript;
+    #lookup;
+    #platform;
+    #watcher;
+    #listeners = new Set();
+    #binding = null;
+    #startAtMs = 0;
+    /** Whether `play track` has been issued for the loaded binding. */
+    #started = false;
+    constructor(options = {}) {
+        this.id = options.id ?? 'spotify-desktop';
+        this.#osascript = options.osascript ?? runOsascript;
+        this.#lookup = options.lookup === undefined ? embedLookup : options.lookup;
+        this.#platform = options.platform ?? process.platform;
+        const intervalMs = options.sampleIntervalMs ?? 1000;
+        this.#watcher = new BackendWatcher({
+            read: async () => parseSample(await this.#osascript(stateScript())),
+            emit: (event) => this.#emit(event),
+            scheduler: options.scheduler ?? systemScheduler,
+            intervalMs,
+            // Two intervals wide: the last reading before a track change can be a
+            // whole interval short of the end, and a window tighter than that reads
+            // every natural rollover as a human taking over.
+            rolloverWindowMs: Math.max(2000, intervalMs * 2),
+            confirmWithin: Math.max(3, Math.ceil(5000 / intervalMs)),
+        });
+    }
+    /**
+     * Fail here rather than at the first song.
+     *
+     * A backend whose `init` throws is excluded from selection and shows up in
+     * `getState().adapters` as `available: false` with the reason — so a host on
+     * Linux gets one clear "this backend is macOS-only" at startup instead of an
+     * agent discovering it one failed track at a time.
+     *
+     * `id of application "Spotify"` resolves the app through LaunchServices
+     * *without launching it*, which is the only way to ask "is Spotify even
+     * installed" that does not open a music player on someone's desktop.
+     */
+    async init() {
+        if (this.#platform !== 'darwin') {
+            throw new SpotifyError('unavailable', `${this.id} drives the macOS Spotify app and cannot run on ${this.#platform}; ` +
+                'use SpotifyWebAdapter instead');
+        }
+        try {
+            await this.#osascript('id of application "Spotify"');
+        }
+        catch (err) {
+            throw new SpotifyError('unavailable', `${this.id} could not find the Spotify desktop app: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Only things that already name a Spotify track.
+     *
+     * Without search there is no way to get from "Bad Habit by Steve Lacy" to a
+     * URI, so scoring anything else above zero would win the ref away from an
+     * adapter that could actually have played it.
+     */
+    match(ref) {
+        const parsed = parseSpotifyUri(ref.uri);
+        return parsed && isPlayableKind(parsed.kind) ? 1 : 0;
+    }
+    async resolve(ref) {
+        const parsed = parseSpotifyUri(ref.uri);
+        if (!parsed || !isPlayableKind(parsed.kind))
+            return null;
+        const nativeUri = toSpotifyUri(parsed);
+        // Best-effort only, and skipped entirely when the ref already says enough.
+        // A track with no title still plays; a resolve that throws does not.
+        let extra = {};
+        if (this.#lookup && !(ref.title && ref.artist)) {
+            try {
+                extra = await this.#lookup(parsed);
+            }
+            catch {
+                extra = {};
+            }
+        }
+        return {
+            adapterId: this.id,
+            nativeUri,
+            // What the caller already knew wins: it came from whoever built the
+            // queue, and the lookup is only filling gaps.
+            ref: { ...extra, ...ref, uri: nativeUri },
+        };
+    }
+    async load(binding, opts) {
+        this.#watcher.stop();
+        this.#binding = binding;
+        this.#startAtMs = opts?.startAtMs ?? 0;
+        this.#started = false;
+    }
+    async play() {
+        const binding = this.#binding;
+        if (!binding)
+            throw new SpotifyError('failed', `${this.id}: nothing is loaded`);
+        if (this.#started) {
+            // Resuming what is already loaded. `play` on its own is the dictionary's
+            // resume; re-issuing `play track` would restart the song from zero.
+            await this.#run(commandScript(commands.play));
+            return;
+        }
+        await this.#run(playTrackScript(binding.nativeUri, this.#startAtMs));
+        this.#started = true;
+        this.#watcher.start(binding.nativeUri);
+    }
+    async pause() {
+        await this.#run(commandScript(commands.pause));
+    }
+    /**
+     * Spotify's dictionary has no stop that does not quit the app, so this
+     * pauses. Quitting somebody's music player because the queue moved on to a
+     * podcast would be a much bigger thing to do than the runtime is asking for.
+     */
+    async stop() {
+        this.#watcher.stop();
+        const wasStarted = this.#started;
+        this.#binding = null;
+        this.#started = false;
+        if (wasStarted)
+            await this.#run(commandScript(commands.pause));
+    }
+    async seek(positionMs) {
+        await this.#run(commandScript(commands.seek(positionMs)));
+    }
+    async setVolume(volume) {
+        await this.#run(commandScript(commands.volume(volume)));
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async dispose() {
+        this.#watcher.stop();
+        this.#listeners.clear();
+        this.#binding = null;
+    }
+    async #run(script) {
+        await this.#osascript(script);
+    }
+    #emit(event) {
+        for (const listener of [...this.#listeners])
+            listener(event);
+    }
+}
+//# sourceMappingURL=desktop.js.map

package/dist/src/desktop.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Why a Spotify call did not work, in the few shapes a caller can act on.
+ *
+ * The distinction that matters is not the status code — it is what the person
+ * holding the machine would have to *do*. "Your token expired" and "you have no
+ * speaker selected" are both a failed play, and an agent that cannot tell them
+ * apart either nags for a re-login when the real problem is a sleeping phone,
+ * or silently retries forever when the real problem is a login.
+ *
+ * Deliberately coarse: the exact wording of an upstream error is not a contract
+ * and will drift, so this keys off the few stable signals and buckets everything
+ * else as `failed`.
+ */
+export type SpotifyFailure = 
+/** No usable session. The host must get a fresh token, or the user must log in. */
+'unauthorized'
+/** Authenticated, but Spotify will not let this account control playback. */
+ | 'premium-required'
+/** Nothing to play *on*: no active device, or the desktop app is not running. */
+ | 'no-device'
+/** Too many calls. Back off; `retryAfterMs` says how long if Spotify said. */
+ | 'rate-limited'
+/** Spotify does not have this track, or not in this market. */
+ | 'not-found'
+/** This backend cannot run here at all — wrong platform, app not installed. */
+ | 'unavailable'
+/** Something else. Renders as "try again", the safe default when unsure. */
+ | 'failed';
+export declare class SpotifyError extends Error {
+    readonly reason: SpotifyFailure;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(reason: SpotifyFailure, message: string, extra?: {
+        status?: number;
+        retryAfterMs?: number;
+    });
+}
+/**
+ * Map an HTTP status, plus Spotify's own `reason` when it sends one, onto a
+ * bucket.
+ *
+ * Two statuses are genuinely ambiguous and the body is what settles them:
+ * a 403 is a scope problem *or* a free account, and a 404 from the player
+ * endpoints is a missing track *or* the well-known `NO_ACTIVE_DEVICE`. Both
+ * distinctions change what a host should tell the user, so both are read.
+ */
+export declare function classifyStatus(status: number, body?: unknown): SpotifyFailure;
+/** Spotify's error body carries a human message worth passing through. */
+export declare function errorMessage(body: unknown, fallback: string): string;
+/**
+ * The same classification against free text, for the backend that has no status
+ * codes — osascript writes prose to stderr and nothing else.
+ *
+ * The ordering matters: rate limiting is tested first because a throttling
+ * message can contain the word "user" and must not be mistaken for the auth
+ * case below it.
+ */
+export declare function classifyText(text: string): SpotifyFailure;
+/** Seconds in a `Retry-After` header, in milliseconds. */
+export declare function retryAfterMs(header: string | null): number | undefined;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc;AACxB,mFAAmF;AACjF,cAAc;AAChB,6EAA6E;GAC3E,kBAAkB;AACpB,iFAAiF;GAC/E,WAAW;AACb,8EAA8E;GAC5E,cAAc;AAChB,+DAA+D;GAC7D,WAAW;AACb,+EAA+E;GAC7E,aAAa;AACf,4EAA4E;GAC1E,QAAQ,CAAC;AAEb,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAG7B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO;CAQzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAW7E;AAWD,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASpE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAazD;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAItE"}