@audiofool/moondog 0.1.0 → 0.2.0-beta.2

package/src/integrations/spotify/web-api-client.mjs

@@ -1,3 +1,5 @@
+import { setTimeout as delay } from "node:timers/promises";
+
 export const SPOTIFY_WEB_API_BASE_URL = "https://api.spotify.com/v1";
 
 export const SPOTIFY_WEB_API_LIMITS = Object.freeze({
@@ -13,6 +15,14 @@ export const SPOTIFY_WEB_API_LIMITS = Object.freeze({
   playlistEditTracksMax: 100,
   libraryItemsMax: 20,
   recentlyPlayedMax: 50,
+  // 429 retry budget for idempotent requests: total attempts (initial plus
+  // up to two retries). Retries are spaced by the server's Retry-After
+  // header when present, with a bounded default and jitter, and never wait
+  // longer than rateLimitMaxWaitMs for a single attempt.
+  rateLimitMaxAttempts: 3,
+  rateLimitDefaultWaitMs: 1_000,
+  rateLimitMaxWaitMs: 10_000,
+  rateLimitJitterMs: 250,
 });
 
 const playbackActions = new Set([
@@ -28,14 +38,29 @@ const playbackActions = new Set([
   "transferring_playback",
 ]);
 
+// Provider error bodies are untrusted and can contain identifiers or credentials.
+// Keep only known machine reasons; never return an arbitrary response message.
+const publicErrorReasons = new Set([
+  "NO_ACTIVE_DEVICE", "PREMIUM_REQUIRED", "RESTRICTION_VIOLATED",
+  "DEVICE_NOT_CONTROLLABLE", "REMOTE_CONTROL_DISALLOW", "CONTEXT_DISALLOW",
+  "NOT_ALLOWED", "TRACK_NOT_PLAYABLE", "CONTENT_UNAVAILABLE", "NON_PLAYABLE",
+  "QUOTA_EXCEEDED", "UNKNOWN", "NO_SPECIFIC_REASON",
+]);
+
+export function spotifyErrorReason(value) {
+  return publicErrorReasons.has(value) ? value : null;
+}
+
 export class SpotifyWebApiError extends Error {
-  constructor(code, message, { status = null, retryAfterSeconds = null } = {}) {
+  constructor(code, message, { status = null, reason = null, retryAfterSeconds = null, outcomeUnknown = false } = {}) {
     super(message);
     this.name = "SpotifyWebApiError";
     this.code = code;
     this.provider = "spotify";
     this.status = status;
+    this.reason = spotifyErrorReason(reason);
     this.retryAfterSeconds = retryAfterSeconds;
+    this.outcomeUnknown = outcomeUnknown;
   }
 }
 
@@ -95,6 +120,16 @@ function retryAfterSeconds(headers) {
   return Math.min(Math.max(0, Math.ceil((date - Date.now()) / 1_000)), 86_400);
 }
 
+// "4 h 11 min", "3 min": how long a wait is, for messages people and the agent read.
+function waitText(seconds) {
+  const minutes = Math.max(1, Math.ceil(seconds / 60));
+  return minutes < 60 ? `${minutes} min` : `${Math.floor(minutes / 60)} h ${minutes % 60} min`;
+}
+
+function defaultSleep(milliseconds, { signal } = {}) {
+  return delay(milliseconds, undefined, { signal });
+}
+
 function quotaReason(payload) {
   if (!isPlainObject(payload)) return undefined;
   return safeText(payload.reason ?? payload.error?.reason, 64);
@@ -107,6 +142,12 @@ function hasInsufficientClientScope(payload) {
   );
 }
 
+function refusalMessage(payload) {
+  if (!isPlainObject(payload)) return undefined;
+  const error = isPlainObject(payload.error) ? payload.error : null;
+  return safeText(error?.message ?? payload.message, 128);
+}
+
 function normalizeArtistNames(rawArtists) {
   if (!Array.isArray(rawArtists)) return [];
   const result = [];
@@ -118,6 +159,22 @@ function normalizeArtistNames(rawArtists) {
   return result;
 }
 
+// Cover art a window can draw: one Spotify CDN image, the largest that is at most 640 pixels.
+function coverImage(images) {
+  const usable = (Array.isArray(images) ? images : []).filter((image) =>
+    typeof image?.url === "string" && /^https:\/\/i\.scdn\.co\/image\/[A-Za-z0-9_-]{1,128}$/u.test(image.url));
+  const sized = usable.filter((image) => !Number.isInteger(image.width) || image.width <= 640)
+    .sort((left, right) => (right.width ?? 0) - (left.width ?? 0));
+  return (sized[0] ?? usable.at(-1))?.url;
+}
+
+// A track's album, kept so a song played alone can go on into the rest of its album.
+// Hosts keep it next to the track URI and never show it to the model.
+function albumUri(raw) {
+  const uri = raw?.album?.uri;
+  return typeof uri === "string" && /^spotify:album:[A-Za-z0-9]{1,128}$/u.test(uri) ? uri : undefined;
+}
+
 function normalizePlayableItem(raw) {
   if (!isPlainObject(raw)) return null;
   const type = ["track", "episode", "ad", "unknown"].includes(raw.type)
@@ -135,9 +192,12 @@ function normalizePlayableItem(raw) {
   if (name) item.name = name;
   if (artists.length > 0) item.artists = artists;
   if (album) item.album = album;
+  if (type === "track" && albumUri(raw)) item.album_uri = albumUri(raw);
   if (publisher) item.publisher = publisher;
   if (durationMs !== undefined) item.duration_ms = durationMs;
   if (typeof raw.explicit === "boolean") item.explicit = raw.explicit;
+  const image = coverImage(raw.album?.images ?? raw.images ?? raw.show?.images);
+  if (image) item.image = image;
   return item;
 }
 
@@ -151,9 +211,9 @@ function normalizeDevice(raw) {
     id,
     name,
     type: type ?? "unknown",
-    is_active: raw.is_active === true,
+    is_active: typeof raw.is_active === "boolean" ? raw.is_active : null,
     is_private_session: raw.is_private_session === true,
-    is_restricted: raw.is_restricted === true,
+    is_restricted: typeof raw.is_restricted === "boolean" ? raw.is_restricted : null,
     supports_volume: raw.supports_volume === true,
   };
   const volume = safeInteger(raw.volume_percent, 0, 100);
@@ -196,14 +256,14 @@ function normalizePlayback(payload) {
   const result = {
     provider: "spotify",
     state: "available",
-    is_playing: payload.is_playing === true,
+    is_playing: typeof payload.is_playing === "boolean" ? payload.is_playing : null,
     shuffle_state: payload.shuffle_state === true,
     repeat_state: ["off", "track", "context"].includes(payload.repeat_state)
       ? payload.repeat_state
       : "off",
     currently_playing_type:
       safeText(payload.currently_playing_type, 32) ?? "unknown",
-    disallowed_actions: normalizeDisallowedActions(payload.actions?.disallows),
+    disallowed_actions: normalizeDisallowedActions(payload.actions?.disallows ?? payload.actions),
   };
   const progressMs = safeInteger(payload.progress_ms, 0, 86_400_000);
   const timestamp = safeInteger(payload.timestamp, 0, Number.MAX_SAFE_INTEGER);
@@ -251,7 +311,7 @@ function normalizeQueue(payload) {
 }
 
 function normalizeTrackSearchItem(raw) {
-  if (!isPlainObject(raw)) return null;
+  if (!isPlainObject(raw) || raw.is_local === true || raw.is_playable === false) return null;
   const uri = safeText(raw.uri);
   const id = safeText(raw.id, 128);
   const name = safeText(raw.name);
@@ -264,6 +324,7 @@ function normalizeTrackSearchItem(raw) {
   };
   const album = safeText(raw.album?.name);
   if (album) item.album = album;
+  if (albumUri(raw)) item.album_uri = albumUri(raw);
   const durationMs = safeInteger(raw.duration_ms, 0, 86_400_000);
   if (durationMs !== undefined) item.duration_ms = durationMs;
   const popularity = safeInteger(raw.popularity, 0, 100);
@@ -272,21 +333,51 @@ function normalizeTrackSearchItem(raw) {
   return item;
 }
 
-function normalizeTrackSearch(payload) {
+function normalizeTrackSearch(payload, { limit = SPOTIFY_WEB_API_LIMITS.searchResultsMax } = {}) {
   const rawItems = Array.isArray(payload?.tracks?.items)
     ? payload.tracks.items
     : [];
   const items = rawItems
     .map(normalizeTrackSearchItem)
     .filter(Boolean)
-    .slice(0, SPOTIFY_WEB_API_LIMITS.searchResultsMax);
+    .slice(0, limit);
+  const hasMore = Boolean(payload?.tracks?.next) || Number.isInteger(payload?.tracks?.total) && rawItems.length < payload.tracks.total;
   return {
     provider: "spotify",
     items,
+    has_more: hasMore,
+    next_offset: hasMore && rawItems.length ? Math.min(rawItems.length, limit) : null,
     truncated: rawItems.length > items.length,
   };
 }
 
+function normalizeCatalogItem(raw, type) {
+  if (type === "track") return normalizeTrackSearchItem(raw);
+  if (!isPlainObject(raw) || !safeText(raw.name) ||
+      typeof raw.uri !== "string" || !new RegExp(`^spotify:${type}:[A-Za-z0-9]{1,128}$`, "u").test(raw.uri)) return null;
+  const item = { type, uri: raw.uri, name: safeText(raw.name), artists: normalizeArtistNames(raw.artists) };
+  for (const field of ["publisher", "release_date"]) if (safeText(raw[field])) item[field] = safeText(raw[field]);
+  const duration = safeInteger(raw.duration_ms, 0, 86_400_000);
+  if (duration !== undefined) item.duration_ms = duration;
+  if (typeof raw.explicit === "boolean") item.explicit = raw.explicit;
+  return item;
+}
+
+function normalizeLibraryPage(payload, type, { limit, offset }) {
+  const raw = Array.isArray(payload?.items) ? payload.items : [];
+  const singular = type.slice(0, -1);
+  const items = raw.slice(0, limit).map((entry) => {
+    const item = normalizeCatalogItem(["playlists", "artists"].includes(type) ? entry : entry?.[singular], singular);
+    const addedAt = normalizedUtcTimestamp(entry?.added_at);
+    return item ? { ...item, ...(addedAt ? { added_at: addedAt } : {}) } : null;
+  }).filter(Boolean);
+  const total = safeInteger(payload?.total, 0, 1_000_000);
+  const hasMore = Boolean(payload?.next) || (total !== undefined && offset + raw.length < total);
+  return { provider: "spotify", type, items, offset, limit, ...(total !== undefined ? { total } : {}),
+    has_more: hasMore, next_offset: hasMore && raw.length > 0 ? offset + Math.min(raw.length, limit) : null,
+    truncated: raw.length > items.length };
+}
+
 function normalizedUtcTimestamp(value) {
   if (typeof value !== "string") return undefined;
   const milliseconds = Date.parse(value);
@@ -311,6 +402,7 @@ function normalizeRecentlyPlayedItem(raw) {
   const artists = normalizeArtistNames(raw.track.artists);
   if (!playedAt || !id || !name || !album || artists.length === 0) return null;
   const track = { id, name, artists, album };
+  if (albumUri(raw.track)) track.album_uri = albumUri(raw.track);
   const durationMs = safeInteger(raw.track.duration_ms, 0, 86_400_000);
   if (durationMs !== undefined) track.duration_ms = durationMs;
   const isrc = safeText(raw.track.external_ids?.isrc, 32);
@@ -339,6 +431,7 @@ function normalizeRecentlyPlayed(payload) {
     provider: "spotify",
     items,
     truncated: rawItems.length > items.length,
+    has_more: Boolean(payload?.next),
     ...(cursorAfterMs !== undefined
       ? { cursor_after_ms: cursorAfterMs }
       : {}),
@@ -358,10 +451,10 @@ function normalizePlaylist(payload, { includeControlMetadata = false } = {}) {
     id,
     uri,
     name,
-    is_public: payload.public === true,
+    is_public: typeof payload.public === "boolean" ? payload.public : null,
   };
   if (includeControlMetadata) {
-    playlist.collaborative = payload.collaborative === true;
+    playlist.collaborative = typeof payload.collaborative === "boolean" ? payload.collaborative : null;
     const ownerId = safeText(payload.owner?.id, 128);
     const snapshotId = safeText(payload.snapshot_id, 128);
     if (ownerId) playlist.owner_id = ownerId;
@@ -398,7 +491,9 @@ function normalizePlaylistPage(payload) {
     total,
     limit,
     offset,
-    has_more: offset + rawItems.length < total,
+    has_more: offset + rawItems.length < total || Boolean(payload?.next),
+    complete_for_name_selection: payload?.offset === 0 && safeInteger(payload?.total, 0, 1_000_000) !== undefined &&
+      rawItems.length === items.length && items.length === payload.total && payload?.next === null,
   };
 }
 
@@ -415,34 +510,45 @@ function normalizePlaylistItem(raw) {
   if (item && typeof source?.is_playable === "boolean") {
     item.is_playable = source.is_playable;
   }
+  const addedAt = normalizedUtcTimestamp(raw.added_at);
   return {
     is_local: raw.is_local === true || source?.is_local === true,
     item,
+    ...(addedAt ? { added_at: addedAt } : {}),
   };
 }
 
 function normalizePlaylistItemsPage(payload) {
   const rawItems = Array.isArray(payload?.items) ? payload.items : [];
+  const offset =
+    safeInteger(payload?.offset, 0, 1_000_000) ?? 0;
   const items = rawItems
     .slice(0, SPOTIFY_WEB_API_LIMITS.playlistItemsPageMax)
     .map(normalizePlaylistItem);
   const total =
     safeInteger(payload?.total, 0, 1_000_000) ?? items.length;
+  if (offset === 0 && total > 0 && rawItems.length === 0) {
+    // The items migration's silent failure mode: a retired playlist-items
+    // path answers 200 with an empty list. Never present that as an empty
+    // playlist — fail so the caller inspects instead of acting on a lie.
+    fail(
+      "spotify_playlist_items_mismatch",
+      `Spotify reported ${total} playlist items but returned none. The playlist may use a retired response shape, or its items are unavailable. Inspect it in the Spotify app before retrying.`,
+    );
+  }
   const limit =
     safeInteger(
       payload?.limit,
       1,
       SPOTIFY_WEB_API_LIMITS.playlistItemsPageMax,
     ) ?? Math.max(1, items.length);
-  const offset =
-    safeInteger(payload?.offset, 0, 1_000_000) ?? 0;
   return {
     provider: "spotify",
     items,
     total,
     limit,
     offset,
-    has_more: offset + rawItems.length < total,
+    has_more: offset + rawItems.length < total || Boolean(payload?.next),
   };
 }
 
@@ -479,6 +585,9 @@ export function createSpotifyWebApiClient({
   fetchImpl = globalThis.fetch,
   tokenProvider,
   baseUrl = SPOTIFY_WEB_API_BASE_URL,
+  sleepImpl = defaultSleep,
+  refreshAccessToken,
+  writeTimeoutMs = 15_000,
 } = {}) {
   if (typeof fetchImpl !== "function") {
     throw new TypeError("A fetch implementation is required.");
@@ -487,157 +596,306 @@ export function createSpotifyWebApiClient({
     throw new TypeError("A Spotify token provider is required.");
   }
   const normalizedBaseUrl = String(baseUrl).replace(/\/+$/u, "");
+  if (!Number.isInteger(writeTimeoutMs) || writeTimeoutMs < 1 || writeTimeoutMs > 60_000) throw new TypeError("Invalid Spotify write settlement timeout.");
+
+  // A 429 re-arms the limiter for the whole client: the server's cooldown
+  // paces later requests too, not just the retried one.
+  let rateLimitResumeAtMs = 0;
+
+  const rearmRateLimit = (waitMs) => {
+    const bounded = Math.min(
+      Math.max(0, waitMs),
+      SPOTIFY_WEB_API_LIMITS.rateLimitMaxWaitMs,
+    );
+    const resumeAt = Date.now() + bounded;
+    if (resumeAt > rateLimitResumeAtMs) rateLimitResumeAtMs = resumeAt;
+  };
+
+  // A used-up development quota answers 429 QUOTA_EXCEEDED with a wait of hours, for some endpoints
+  // only. Asking again before then gets the same answer, so until the time Spotify gave, the client
+  // answers for that endpoint itself and sends nothing.
+  const quotaResumeAtMs = new Map();
+  const quotaExhausted = (retryAfter, options) => fail("spotify_quota_exceeded",
+    `Spotify development quota is exhausted.${retryAfter ? ` Spotify allows this request again in about ${waitText(retryAfter)}.` : ""}`,
+    { ...options, status: 429, reason: "QUOTA_EXCEEDED", retryAfterSeconds: retryAfter });
 
   const request = async (
     path,
-    { method = "GET", body, responseMode = "json" } = {},
+    { method = "GET", body, responseMode = "json", signal, beforeDispatch } = {},
   ) => {
-    const token = normalizedToken(await tokenProvider());
-    const headers = {
-      accept: "application/json",
-      authorization: `Bearer ${token}`,
+    const endpoint = String(path).split("?")[0];
+    const quotaWaitMs = (quotaResumeAtMs.get(endpoint) ?? 0) - Date.now();
+    if (quotaWaitMs > 0) quotaExhausted(Math.ceil(quotaWaitMs / 1_000), { outcomeUnknown: false });
+    const initForToken = (token) => {
+      const headers = {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+      };
+      const init = { method, headers };
+      if (body !== undefined) {
+        headers["content-type"] = "application/json";
+        init.body = JSON.stringify(body);
+      }
+      return init;
     };
-    const init = { method, headers };
-    if (body !== undefined) {
-      headers["content-type"] = "application/json";
-      init.body = JSON.stringify(body);
-    }
-
-    let response;
-    try {
-      response = await fetchImpl(`${normalizedBaseUrl}${path}`, init);
-    } catch {
-      fail("spotify_network_error", "Spotify could not be reached.");
-    }
 
-    if (response.ok && (response.status === 204 || responseMode === "none")) {
-      return null;
-    }
-    const text = await response.text();
-    if (text.length > SPOTIFY_WEB_API_LIMITS.responseBytesMax) {
-      fail("spotify_response_too_large", "Spotify returned too much data.", {
-        status: response.status,
-      });
-    }
-    let payload = null;
-    if (text) {
+    // Read recovery shares one request budget. Every write gets one dispatch;
+    // a rejected token may be refreshed for a later explicitly requested action.
+    const read = method === "GET";
+    const maxAttempts = read ? SPOTIFY_WEB_API_LIMITS.rateLimitMaxAttempts : 1;
+    const accessToken = async (operation) => {
+      try {
+        return normalizedToken(await operation());
+      } catch (error) {
+        // Token lookup occurs before dispatch, or after a definite 401. Its
+        // failure cannot turn the protected write into an unknown effect.
+        if (!read && error && typeof error === "object") error.outcomeUnknown = false;
+        throw error;
+      }
+    };
+    signal?.throwIfAborted();
+    let token = await accessToken(() => tokenProvider({ signal }));
+    let refreshed = false;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      // Recheck before every dispatch, including after refresh or retry backoff.
+      // Another in-flight 429 can extend the deadline while this request sleeps.
+      // Backoff already elapsed; wait only for any remaining shared cooldown.
+      while (true) {
+        signal?.throwIfAborted();
+        const remainingMs = rateLimitResumeAtMs - Date.now();
+        if (remainingMs <= 0) break;
+        await sleepImpl(remainingMs, { signal });
+      }
+      const init = initForToken(token);
+      // Let a dispatched write settle so cancellation cannot hide its receipt.
+      if (read && signal) init.signal = signal;
+      const deadline = Date.now() + writeTimeoutMs;
+      const transport = read ? null : new AbortController();
+      if (transport) init.signal = transport.signal;
+      const settle = async (operation) => {
+        if (read) return operation();
+        let timer;
+        try {
+          return await Promise.race([Promise.resolve(operation()), new Promise((_, reject) => {
+            timer = setTimeout(() => {
+              transport.abort();
+              reject(new Error("Spotify write settlement deadline exceeded."));
+            }, Math.max(0, deadline - Date.now()));
+          })]);
+        } finally { clearTimeout(timer); }
+      };
+      let response;
+      // A host authority guard runs after async token/refresh/lock waiting.
+      // Local refusal precedes fetch and must not become an uncertain write.
+      beforeDispatch?.();
+      try {
+        response = await settle(() => fetchImpl(`${normalizedBaseUrl}${path}`, init));
+      } catch (error) {
+        if (read) {
+          signal?.throwIfAborted();
+          if (error?.name === "AbortError") throw error;
+        }
+        // Writes have no transport cancellation signal: a transport AbortError
+        // cannot prove that the dispatched action had no effect.
+        fail("spotify_network_error", "Spotify could not be reached.", { outcomeUnknown: !read });
+      }
+      if (read) signal?.throwIfAborted();
+      if (response.ok && (response.status === 204 || responseMode === "none")) return null;
+      let text;
       try {
-        payload = JSON.parse(text);
-      } catch {
-        fail("spotify_response_invalid", "Spotify returned an invalid response.", {
+        text = await settle(() => response.text());
+      } catch (error) {
+        if (read) {
+          signal?.throwIfAborted();
+          if (error?.name === "AbortError") throw error;
+        }
+        fail("spotify_network_error", "Spotify's response could not be read.", {
           status: response.status,
+          outcomeUnknown: !read && !(response.status >= 400 && response.status < 500),
         });
       }
-    }
-
-    if (!response.ok) {
-      const options = {
-        status: response.status,
-        retryAfterSeconds: retryAfterSeconds(response.headers),
-      };
-      if (response.status === 401) {
-        fail(
-          "spotify_authentication_required",
-          "Spotify authentication must be refreshed.",
-          options,
-        );
+      if (read) signal?.throwIfAborted();
+      if (Buffer.byteLength(text, "utf8") > SPOTIFY_WEB_API_LIMITS.responseBytesMax) {
+        fail("spotify_response_too_large", "Spotify returned too much data.", {
+          status: response.status,
+          outcomeUnknown: !read && !(response.status >= 400 && response.status < 500),
+        });
       }
-      if (response.status === 403) {
-        if (hasInsufficientClientScope(payload)) {
-          fail(
-            "spotify_scope_insufficient",
-            "Spotify authorization is missing a required scope. Run moondog spotify login again.",
-            options,
-          );
+      let payload = null;
+      if (text) {
+        try { payload = JSON.parse(text); } catch {
+          // Error responses can be plain text. Their HTTP status still decides
+          // whether authentication or a bounded read retry is appropriate.
+          if (response.ok) fail("spotify_response_invalid", "Spotify returned an invalid response.", { status: response.status, outcomeUnknown: !read });
         }
-        fail(
-          "spotify_action_forbidden",
-          "Spotify did not allow this action.",
-          options,
-        );
+      }
+      if (response.ok) return payload;
+      const retryAfter = retryAfterSeconds(response.headers);
+      const options = { status: response.status, reason: quotaReason(payload), retryAfterSeconds: retryAfter,
+        outcomeUnknown: !read && response.status >= 500 };
+      if (response.status === 401) {
+        if (!refreshed && typeof refreshAccessToken === "function" && (!read || attempt < maxAttempts)) {
+          signal?.throwIfAborted();
+          token = await accessToken(() => refreshAccessToken({ signal, rejectedAccessToken: token }));
+          refreshed = true;
+          if (!read) {
+            signal?.throwIfAborted();
+            fail("spotify_action_not_replayed", "Spotify rejected this action. Authentication was refreshed, but the action was not replayed. Submit a new request if you still want it.", options);
+          }
+          continue;
+        }
+        fail("spotify_authentication_required", "Spotify authentication must be refreshed.", options);
       }
       if (response.status === 429) {
         if (quotaReason(payload) === "QUOTA_EXCEEDED") {
-          fail(
-            "spotify_quota_exceeded",
-            "Spotify development quota is exhausted.",
-            options,
-          );
+          if (retryAfter) quotaResumeAtMs.set(endpoint, Date.now() + retryAfter * 1_000);
+          quotaExhausted(retryAfter, options);
+        }
+        const waitMs = retryAfter === null ? SPOTIFY_WEB_API_LIMITS.rateLimitDefaultWaitMs : retryAfter * 1_000;
+        rearmRateLimit(waitMs);
+        if (read && attempt < maxAttempts && waitMs <= SPOTIFY_WEB_API_LIMITS.rateLimitMaxWaitMs) {
+          signal?.throwIfAborted();
+          const jittered = Math.min(SPOTIFY_WEB_API_LIMITS.rateLimitMaxWaitMs,
+            waitMs + Math.floor(Math.random() * SPOTIFY_WEB_API_LIMITS.rateLimitJitterMs));
+          await sleepImpl(jittered, { signal });
+          continue;
         }
-        fail(
-          "spotify_rate_limited",
-          "Spotify rate limited this request.",
-          options,
-        );
+        fail("spotify_rate_limited", "Spotify rate limited this request.", options);
+      }
+      if (response.status === 403) {
+        if (hasInsufficientClientScope(payload)) {
+          fail("spotify_scope_insufficient", "Spotify authorization is missing a required scope. Run moondog spotify login again.", options);
+        }
+        if (refusalMessage(payload) === undefined) {
+          // The items migration's signature: retired or app-restricted
+          // endpoints answer 403 with no helpful body. Report that
+          // distinctly instead of a generic forbidden action.
+          fail("spotify_endpoint_retired", "Spotify refused this request without detail. The endpoint or content may have been retired or restricted for this app after Spotify's items migration.", options);
+        }
+        fail("spotify_action_forbidden", "Spotify did not allow this action.", options);
       }
       fail("spotify_api_error", "Spotify rejected this request.", options);
     }
-    return payload;
   };
 
   return Object.freeze({
-    async getAccount() {
-      return normalizeAccount(await request("/me"));
+    async getAccount({ signal } = {}) {
+      return normalizeAccount(await request("/me", { signal }));
     },
 
-    async getCurrentPlayback() {
-      return normalizePlayback(await request("/me/player"));
+    async getCurrentPlayback({ signal } = {}) {
+      return normalizePlayback(await request("/me/player?additional_types=episode", { signal }));
     },
 
-    async getDevices() {
-      return normalizeDevices(await request("/me/player/devices"));
+    async getDevices({ signal } = {}) {
+      return normalizeDevices(await request("/me/player/devices", { signal }));
     },
 
-    async getQueue() {
-      return normalizeQueue(await request("/me/player/queue"));
+    async getQueue({ signal } = {}) {
+      return normalizeQueue(await request("/me/player/queue", { signal }));
     },
 
-    async getRecentlyPlayed({ limit, after, before } = {}) {
+    async getRecentlyPlayed({ limit, after, before } = {}, { signal } = {}) {
       return normalizeRecentlyPlayed(
         await request(
-          `/me/player/recently-played${queryString({ limit, after, before })}`,
+          `/me/player/recently-played${queryString({ limit, after, before })}`, { signal },
         ),
       );
     },
 
-    async searchTracks({ query, limit, market } = {}) {
+    // Agent browsing is capped by the service; a library import reads Spotify's full page of 50.
+    async getSavedItems({ type = "tracks", limit = 20, offset = 0 } = {}, { signal } = {}) {
+      if (!["tracks", "albums", "shows", "playlists"].includes(type) || !Number.isInteger(limit) || limit < 1 || limit > 50 ||
+          !Number.isInteger(offset) || offset < 0 || offset > 1_000_000) fail("invalid_library_page", "Choose a supported library type and bounded page.");
+      return normalizeLibraryPage(await request(`/me/${type}${queryString({ limit, offset })}`, { signal }), type, { limit, offset });
+    },
+
+    async getFollowedArtists({ limit = 10, after } = {}, { signal } = {}) {
+      const payload = await request(`/me/following${queryString({ type: "artist", limit, after })}`, { signal });
+      const result = normalizeLibraryPage(payload?.artists, "artists", { limit, offset: 0 });
+      delete result.next_offset;
+      result.has_more = Boolean(payload?.artists?.next);
+      const cursor = payload?.artists?.cursors?.after;
+      if (result.has_more && typeof cursor === "string" && cursor !== after && /^[A-Za-z0-9]{1,128}$/u.test(cursor)) result.next_after = cursor;
+      return result;
+    },
+
+    async searchItems({ query, type, limit, offset = 0 } = {}, { signal } = {}) {
+      const payload = await request(`/search${queryString({ q: query, type, limit, offset })}`, { signal });
+      const page = payload?.[`${type}s`];
+      const raw = Array.isArray(page?.items) ? page.items : [];
+      const items = raw.slice(0, limit).map((item) => normalizeCatalogItem(item, type)).filter(Boolean);
+      const hasMore = Boolean(page?.next) || Number.isInteger(page?.total) && offset + raw.length < page.total;
+      return { provider: "spotify", type, items, has_more: hasMore,
+        next_offset: hasMore && raw.length ? offset + Math.min(raw.length, limit) : null,
+        truncated: raw.length > items.length };
+    },
+
+    async getCatalogChildren({ type, id, limit, offset } = {}, { signal } = {}) {
+      const childType = type === "album" ? "track" : "episode";
+      const payload = await request(`/${type}s/${encodeURIComponent(id)}/${childType}s${queryString({ limit, offset })}`, { signal });
+      const raw = Array.isArray(payload?.items) ? payload.items : [];
+      const items = raw.slice(0, limit).map((item) => normalizeCatalogItem(item, childType)).filter(Boolean);
+      const hasMore = Boolean(payload?.next) || Number.isInteger(payload?.total) && offset + raw.length < payload.total;
+      return { provider: "spotify", source: "catalog", items, limit, offset, has_more: hasMore,
+        next_offset: hasMore && raw.length ? offset + Math.min(raw.length, limit) : null, truncated: raw.length > items.length };
+    },
+
+    async searchTracks({ query, limit, market } = {}, { signal } = {}) {
       return normalizeTrackSearch(
         await request(
-          `/search${queryString({ q: query, type: "track", limit, market })}`,
-        ),
+          `/search${queryString({ q: query, type: "track", limit, market })}`, { signal },
+        ), { limit },
       );
     },
 
-    async getCurrentUserPlaylists({ limit, offset } = {}) {
+    async getTopItems({ type = "tracks", timeRange = "medium_term", limit = 5 } = {}, { signal } = {}) {
+      if (!["artists", "tracks"].includes(type) || !["short_term", "medium_term", "long_term"].includes(timeRange) ||
+          !Number.isInteger(limit) || limit < 1 || limit > 50) {
+        fail("invalid_top_items", "Spotify top items require a supported type, time range, and limit from 1 to 50.");
+      }
+      const payload = await request(`/me/top/${type}${queryString({ time_range: timeRange, limit, offset: 0 })}`, { signal });
+      const raw = Array.isArray(payload?.items) ? payload.items : [];
+      const items = raw.slice(0, limit).map((item, index) => {
+        const artistUri = typeof item?.uri === "string" && /^spotify:artist:[A-Za-z0-9]{22}$/u.test(item.uri) ? item.uri : null;
+        const normalized = type === "tracks" ? normalizeTrackSearchItem(item) :
+          (safeText(item?.name) ? { name: safeText(item.name), type: "artist", ...(artistUri ? { uri: artistUri } : {}) } : null);
+        return normalized ? { ...normalized, affinity_rank: index + 1 } : null;
+      }).filter(Boolean);
+      return { provider: "spotify", items, truncated: raw.length > items.length || Boolean(payload?.next) || payload?.total > raw.length };
+    },
+
+    async getCurrentUserPlaylists({ limit, offset } = {}, { signal } = {}) {
       return normalizePlaylistPage(
         await request(
-          `/me/playlists${queryString({ limit, offset })}`,
+          `/me/playlists${queryString({ limit, offset })}`, { signal },
         ),
       );
     },
 
-    async getPlaylist({ playlistId } = {}) {
+    async getPlaylist({ playlistId } = {}, { signal } = {}) {
       return normalizePlaylist(
-        await request(`/playlists/${encodeURIComponent(playlistId)}`),
+        await request(`/playlists/${encodeURIComponent(playlistId)}`, { signal }),
         { includeControlMetadata: true },
       );
     },
 
-    async getPlaylistItems({ playlistId, limit, offset } = {}) {
+    async getPlaylistItems({ playlistId, limit, offset } = {}, { signal } = {}) {
       return normalizePlaylistItemsPage(
         await request(
           `/playlists/${encodeURIComponent(playlistId)}/items${queryString({
             limit,
             offset,
-          })}`,
+          })}`, { signal },
         ),
       );
     },
 
-    async createPlaylist({ name, description } = {}) {
+    async createPlaylist({ name, description } = {}, { signal } = {}) {
       return normalizePlaylist(
         await request("/me/playlists", {
           method: "POST",
+          signal,
           body: {
             name,
             ...(description ? { description } : {}),
@@ -647,114 +905,136 @@ export function createSpotifyWebApiClient({
       );
     },
 
-    async addPlaylistTracks({ playlistId, uris } = {}) {
+    async addPlaylistTracks({ playlistId, uris } = {}, { signal } = {}) {
       const payload = await request(
         `/playlists/${encodeURIComponent(playlistId)}/items`,
-        { method: "POST", body: { uris } },
+        { method: "POST", body: { uris }, signal },
       );
       const snapshotId = safeText(payload?.snapshot_id, 128);
       return snapshotId ? { snapshot_id: snapshotId } : {};
     },
 
-    async replacePlaylistItems({ playlistId, uris } = {}) {
+    async renamePlaylist({ playlistId, name } = {}, { signal, beforeDispatch } = {}) {
+      await request(`/playlists/${encodeURIComponent(playlistId)}`, {
+        method: "PUT", body: { name }, responseMode: "none", signal, beforeDispatch,
+      });
+    },
+
+    async removePlaylistItem({ playlistId, uri, snapshotId } = {}, { signal, beforeDispatch } = {}) {
+      const payload = await request(`/playlists/${encodeURIComponent(playlistId)}/items`, {
+        method: "DELETE", body: { items: [{ uri }], snapshot_id: snapshotId }, signal, beforeDispatch,
+      });
+      const snapshot = safeText(payload?.snapshot_id, 128);
+      if (!snapshot) fail("spotify_write_receipt_invalid", "Spotify did not return a valid removal receipt. Inspect the playlist before retrying.", { outcomeUnknown: true });
+      return { snapshot_id: snapshot };
+    },
+
+    async replacePlaylistItems({ playlistId, uris } = {}, { signal } = {}) {
       const payload = await request(
         `/playlists/${encodeURIComponent(playlistId)}/items`,
-        { method: "PUT", body: { uris } },
+        { method: "PUT", body: { uris }, signal },
       );
       const snapshotId = safeText(payload?.snapshot_id, 128);
       return snapshotId ? { snapshot_id: snapshotId } : {};
     },
 
-    async checkSavedTracks({ uris } = {}) {
+    async checkSavedTracks({ uris } = {}, { signal } = {}) {
       return normalizeSavedContains(
         await request(
-          `/me/library/contains${queryString({ uris: uris.join(",") })}`,
+          `/me/library/contains${queryString({ uris: uris.join(",") })}`, { signal },
         ),
       );
     },
 
-    async saveTracks({ uris } = {}) {
+    async saveTracks({ uris } = {}, { signal } = {}) {
       await request(`/me/library${queryString({ uris: uris.join(",") })}`, {
         method: "PUT",
         responseMode: "none",
+        signal,
       });
       return null;
     },
 
-    async resume(input = {}) {
+    async removeLibraryItems({ uris } = {}, { signal } = {}) {
+      await request(`/me/library${queryString({ uris: uris.join(",") })}`, { method: "DELETE", responseMode: "none", signal });
+    },
+
+    async resume(input = {}, { signal, beforeDispatch } = {}) {
       await request(
         `/me/player/play${queryString({ device_id: input.deviceId })}`,
-        { method: "PUT", body: playbackBody(input), responseMode: "none" },
+        { method: "PUT", body: playbackBody(input), responseMode: "none", signal, beforeDispatch },
       );
     },
 
-    async pause({ deviceId } = {}) {
+    async pause({ deviceId } = {}, { signal } = {}) {
       await request(
         `/me/player/pause${queryString({ device_id: deviceId })}`,
-        { method: "PUT", responseMode: "none" },
+        { method: "PUT", responseMode: "none", signal },
       );
     },
 
-    async next({ deviceId } = {}) {
+    async next({ deviceId } = {}, { signal } = {}) {
       await request(
         `/me/player/next${queryString({ device_id: deviceId })}`,
-        { method: "POST", responseMode: "none" },
+        { method: "POST", responseMode: "none", signal },
       );
     },
 
-    async previous({ deviceId } = {}) {
+    async previous({ deviceId } = {}, { signal } = {}) {
       await request(
         `/me/player/previous${queryString({ device_id: deviceId })}`,
-        { method: "POST", responseMode: "none" },
+        { method: "POST", responseMode: "none", signal },
       );
     },
 
-    async setVolume({ percent, deviceId }) {
+    async setVolume({ percent, deviceId }, { signal } = {}) {
       await request(
         `/me/player/volume${queryString({
           volume_percent: percent,
           device_id: deviceId,
         })}`,
-        { method: "PUT", responseMode: "none" },
+        { method: "PUT", responseMode: "none", signal },
       );
     },
 
-    async seek({ positionMs, deviceId }) {
+    async seek({ positionMs, deviceId }, { signal } = {}) {
       await request(
         `/me/player/seek${queryString({
           position_ms: positionMs,
           device_id: deviceId,
         })}`,
-        { method: "PUT", responseMode: "none" },
+        { method: "PUT", responseMode: "none", signal },
       );
     },
 
-    async setShuffle({ state, deviceId }) {
+    async setShuffle({ state, deviceId }, { signal } = {}) {
       await request(
         `/me/player/shuffle${queryString({ state, device_id: deviceId })}`,
-        { method: "PUT", responseMode: "none" },
+        { method: "PUT", responseMode: "none", signal },
       );
     },
 
-    async setRepeat({ state, deviceId }) {
+    async setRepeat({ state, deviceId }, { signal } = {}) {
       await request(
         `/me/player/repeat${queryString({ state, device_id: deviceId })}`,
-        { method: "PUT", responseMode: "none" },
+        { method: "PUT", responseMode: "none", signal },
       );
     },
 
-    async transfer({ deviceId, play }) {
+    async transfer({ deviceId, play }, { signal, beforeDispatch } = {}) {
       await request("/me/player", {
         method: "PUT",
         body: { device_ids: [deviceId], play },
         responseMode: "none",
+        signal,
+        beforeDispatch,
       });
     },
 
-    async addToQueue({ uri, deviceId }) {
+    async addToQueue({ uri, deviceId }, { signal } = {}) {
       await request(
         `/me/player/queue${queryString({ uri, device_id: deviceId })}`,
-        { method: "POST", responseMode: "none" },
+        { method: "POST", responseMode: "none", signal },
       );
     },
   });