upnext-adapter-spotify 0.1.0

package/dist/src/errors.js

@@ -0,0 +1,93 @@
+export class SpotifyError extends Error {
+    reason;
+    status;
+    retryAfterMs;
+    constructor(reason, message, extra = {}) {
+        super(message);
+        this.name = 'SpotifyError';
+        this.reason = reason;
+        if (extra.status !== undefined)
+            this.status = extra.status;
+        if (extra.retryAfterMs !== undefined)
+            this.retryAfterMs = extra.retryAfterMs;
+    }
+}
+/**
+ * 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 function classifyStatus(status, body) {
+    const reason = errorReason(body);
+    if (status === 429)
+        return 'rate-limited';
+    if (status === 401)
+        return 'unauthorized';
+    if (status === 403) {
+        return reason === 'PREMIUM_REQUIRED' ? 'premium-required' : 'unauthorized';
+    }
+    if (status === 404) {
+        return reason === 'NO_ACTIVE_DEVICE' ? 'no-device' : 'not-found';
+    }
+    return 'failed';
+}
+/** Spotify's player errors carry `{ error: { status, message, reason } }`. */
+function errorReason(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const error = body.error;
+    if (!error || typeof error !== 'object')
+        return null;
+    const reason = error.reason;
+    return typeof reason === 'string' ? reason : null;
+}
+/** Spotify's error body carries a human message worth passing through. */
+export function errorMessage(body, fallback) {
+    if (!body || typeof body !== 'object')
+        return fallback;
+    const error = body.error;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object') {
+        const message = error.message;
+        if (typeof message === 'string' && message.trim())
+            return message.trim();
+    }
+    return fallback;
+}
+/**
+ * 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 function classifyText(text) {
+    const lower = text.toLowerCase();
+    if (/rate limit|too many|429/.test(lower))
+        return 'rate-limited';
+    if (/not authorized|not authorised|-1743|assistive access/.test(lower)) {
+        // macOS Automation consent was declined. Not a Spotify login problem, but
+        // it is the same shape of problem: a permission the user has to grant.
+        return 'unauthorized';
+    }
+    if (/(-600|-609)|isn't running|is not running|application isn't/.test(lower)) {
+        return 'no-device';
+    }
+    if (/can't get|cant get|-1728/.test(lower))
+        return 'not-found';
+    return 'failed';
+}
+/** Seconds in a `Retry-After` header, in milliseconds. */
+export function retryAfterMs(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number.parseInt(header, 10);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

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

package/dist/src/http.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare class SpotifyHttp {
+    #private;
+    constructor(options: SpotifyHttpOptions);
+    request(method: 'GET' | 'PUT' | 'POST', path: string, options?: RequestOptions): Promise<unknown>;
+    /** Drop the cached token, so the next call asks the host for a new one. */
+    invalidate(): void;
+}
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,aAAa,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW;;gBAQV,OAAO,EAAE,kBAAkB;IAMjC,OAAO,CACX,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC;IASnB,2EAA2E;IAC3E,UAAU,IAAI,IAAI;CAwEnB"}

package/dist/src/http.js

@@ -0,0 +1,113 @@
+import { SpotifyError, classifyStatus, errorMessage, retryAfterMs } from './errors.js';
+/**
+ * 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;
+    #fetch;
+    #baseUrl;
+    #token = null;
+    #fetching = null;
+    constructor(options) {
+        this.#getAccessToken = options.getAccessToken;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#baseUrl = (options.baseUrl ?? 'https://api.spotify.com/v1').replace(/\/$/, '');
+    }
+    async request(method, path, options = {}) {
+        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() {
+        this.#token = null;
+    }
+    async #send(method, path, options, token) {
+        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 = { 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, options) {
+        // 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) {
+        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) {
+    try {
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/http.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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';
+export { parseSpotifyUri, toSpotifyUri, toSpotifyUrl, isPlayableKind } from './uri.js';
+export type { SpotifyId, SpotifyKind } from './uri.js';
+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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACvF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAIvD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,EACf,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,28 @@
+/**
+ * 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 { SpotifyWebAdapter, toSample } from './web.js';
+export { SpotifyHttp } from './http.js';
+export { SpotifyError, classifyStatus, classifyText } from './errors.js';
+// Identity helpers, for hosts normalising links a person pasted.
+export { parseSpotifyUri, toSpotifyUri, toSpotifyUrl, isPlayableKind } 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 { BackendWatcher } from './watch.js';
+export { parseSample, stateScript, playTrackScript, commandScript, commands, runOsascript, FIELD, } from './applescript.js';
+export { embedLookup, readEmbedHtml, clearMetadataCache } from './metadata.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzE,iEAAiE;AACjE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvF,+EAA+E;AAC/E,4DAA4D;AAC5D,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,EACf,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,KAAK,GACN,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/metadata.d.ts

@@ -0,0 +1,39 @@
+import type { MediaRef } from 'upnext-core';
+import { 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>>;
+/** Everything the queue would want to show, from the public embed page. */
+export declare const embedLookup: TrackLookup;
+/** Drop everything remembered. Exported for tests; a host has no reason to. */
+export declare function clearMetadataCache(): void;
+/**
+ * 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 declare function readEmbedHtml(html: string): Partial<MediaRef>;
+//# sourceMappingURL=metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AAgBxE,2EAA2E;AAC3E,eAAO,MAAM,WAAW,EAAE,WAQzB,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAmBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+C7D"}

package/dist/src/metadata.js

@@ -0,0 +1,130 @@
+import { toSpotifyUri } from './uri.js';
+const EMPTY = {};
+/**
+ * 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();
+/** Everything the queue would want to show, from the public embed page. */
+export const embedLookup = 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() {
+    cache.clear();
+}
+async function fetchEmbed(parsed) {
+    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) {
+    const match = html.match(/<script id="__NEXT_DATA__" type="application\/json">(.*?)<\/script>/s);
+    if (!match?.[1])
+        return EMPTY;
+    let data;
+    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;
+    const out = {};
+    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.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
+        : {};
+    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) {
+    if (!Array.isArray(images))
+        return null;
+    const sized = [];
+    for (const image of images) {
+        if (!image || typeof image !== 'object')
+            continue;
+        const record = image;
+        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, keys) {
+    let current = value;
+    for (const key of keys) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+//# sourceMappingURL=metadata.js.map

package/dist/src/metadata.js.map

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

package/dist/src/ref.d.ts

@@ -0,0 +1,29 @@
+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 declare function readTrack(value: unknown): MediaRef | 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 declare function searchQuery(ref: MediaRef): string | null;
+//# sourceMappingURL=ref.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CA+CzD;AAqDD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAOxD"}