@crafter/spoti-cli 0.1.1 → 0.2.0

package/dist/index.js

@@ -74,6 +74,22 @@ import { homedir } from "os";
 import { join } from "path";
 var CONFIG_DIR = join(homedir(), ".spoti-cli");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var LEGACY_SCOPES = [
+  "playlist-modify-private",
+  "playlist-modify-public",
+  "user-read-private",
+  "user-read-email"
+];
+function requireScopes(needed) {
+  const config = readConfig();
+  const granted = config.scopes ?? LEGACY_SCOPES;
+  const missing = needed.filter((s) => !granted.includes(s));
+  if (missing.length > 0) {
+    console.error(`This command requires additional permissions: ${missing.join(", ")}`);
+    console.error("Run: spoti-cli auth --upgrade");
+    process.exit(1);
+  }
+}
 function ensureConfigDir() {
   if (!existsSync(CONFIG_DIR)) {
     mkdirSync(CONFIG_DIR, { recursive: true });
@@ -94,12 +110,22 @@ function updateConfig(partial) {
 }
 
 // src/commands/auth.ts
-var SCOPES = [
+var BASE_SCOPES = [
   "playlist-modify-private",
   "playlist-modify-public",
   "user-read-private",
   "user-read-email"
 ];
+var FULL_SCOPES = [
+  ...BASE_SCOPES,
+  "user-read-playback-state",
+  "user-modify-playback-state",
+  "user-read-currently-playing",
+  "user-top-read",
+  "user-library-read",
+  "user-library-modify",
+  "user-read-recently-played"
+];
 function generateCodeVerifier() {
   const array = new Uint8Array(64);
   crypto.getRandomValues(array);
@@ -111,7 +137,7 @@ async function generateCodeChallenge(verifier) {
   const digest = await crypto.subtle.digest("SHA-256", data);
   return btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
 }
-async function authCommand(clientId) {
+async function authCommand(clientId, upgrade = false) {
   const config = readConfig();
   const id = clientId ?? config.client_id;
   if (!id) {
@@ -125,7 +151,8 @@ async function authCommand(clientId) {
   const authUrl = new URL("https://accounts.spotify.com/authorize");
   authUrl.searchParams.set("response_type", "code");
   authUrl.searchParams.set("client_id", id);
-  authUrl.searchParams.set("scope", SCOPES.join(" "));
+  const scopes = upgrade ? [.../* @__PURE__ */ new Set([...config.scopes ?? BASE_SCOPES, ...FULL_SCOPES])] : FULL_SCOPES;
+  authUrl.searchParams.set("scope", scopes.join(" "));
   authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
   authUrl.searchParams.set("code_challenge_method", "S256");
   authUrl.searchParams.set("code_challenge", codeChallenge);
@@ -155,7 +182,8 @@ async function authCommand(clientId) {
   updateConfig({
     access_token: data.access_token,
     refresh_token: data.refresh_token,
-    expires_at: Date.now() + data.expires_in * 1e3
+    expires_at: Date.now() + data.expires_in * 1e3,
+    scopes
   });
   console.log("Authenticated successfully!");
   console.log("");
@@ -252,6 +280,74 @@ async function spotify(path, options = {}) {
   return res.json();
 }
 
+// src/commands/artist.ts
+async function artistGetCommand(id, opts) {
+  const data = await spotify(`/artists/${id}`);
+  const result = {
+    id: data.id,
+    name: data.name,
+    genres: data.genres.join(", "),
+    popularity: data.popularity,
+    followers: data.followers.total,
+    uri: data.uri,
+    url: data.external_urls.spotify
+  };
+  output(result, opts.json);
+}
+async function artistTopTracksCommand(id, opts) {
+  const market = opts.market || "US";
+  const data = await spotify(
+    `/artists/${id}/top-tracks?market=${market}`
+  );
+  const items = data.tracks.map((t) => ({
+    id: t.id,
+    name: t.name,
+    artist: t.artists.map((a) => a.name).join(", "),
+    album: t.album.name,
+    popularity: t.popularity,
+    uri: t.uri
+  }));
+  output(items, opts.json);
+}
+async function artistAlbumsCommand(id, opts) {
+  const limit = opts.limit || "20";
+  const data = await spotify(
+    `/artists/${id}/albums?limit=${limit}&include_groups=album,single`
+  );
+  const items = data.items.map((a) => ({
+    id: a.id,
+    name: a.name,
+    type: a.album_type,
+    released: a.release_date,
+    tracks: a.total_tracks,
+    uri: a.uri
+  }));
+  output(items, opts.json);
+}
+async function artistRelatedCommand(id, opts) {
+  let data;
+  try {
+    data = await spotify(
+      `/artists/${id}/related-artists`
+    );
+  } catch (err) {
+    if (err instanceof Error && (err.message.includes("403") || err.message.includes("404"))) {
+      console.error("Related artists endpoint is restricted by Spotify. This may require an approved app.");
+      process.exit(1);
+    }
+    throw err;
+  }
+  const items = data.artists.map((a) => ({
+    id: a.id,
+    name: a.name,
+    genres: a.genres.join(", "),
+    popularity: a.popularity,
+    followers: a.followers.total,
+    uri: a.uri
+  }));
+  output(items, opts.json);
+}
+
 // src/commands/create.ts
 async function createCommand(name, opts) {
   const user = await spotify("/me");
@@ -291,6 +387,74 @@ async function createCommand(name, opts) {
   }
 }
 
+// src/commands/history.ts
+var HISTORY_SCOPES = ["user-read-recently-played"];
+async function historyCommand(opts) {
+  requireScopes(HISTORY_SCOPES);
+  const limit = opts.limit || "20";
+  const data = await spotify(
+    `/me/player/recently-played?limit=${limit}`
+  );
+  const items = data.items.map((i) => ({
+    id: i.track.id,
+    name: i.track.name,
+    artist: i.track.artists.map((a) => a.name).join(", "),
+    album: i.track.album.name,
+    played_at: i.played_at,
+    uri: i.track.uri
+  }));
+  output(items, opts.json);
+}
+
+// src/commands/library.ts
+var LIBRARY_READ_SCOPES = ["user-library-read"];
+var LIBRARY_WRITE_SCOPES = ["user-library-read", "user-library-modify"];
+async function libraryListCommand(opts) {
+  requireScopes(LIBRARY_READ_SCOPES);
+  const limit = opts.limit || "20";
+  const offset = opts.offset || "0";
+  const data = await spotify(
+    `/me/tracks?limit=${limit}&offset=${offset}`
+  );
+  const items = data.items.map((i) => ({
+    id: i.track.id,
+    name: i.track.name,
+    artist: i.track.artists.map((a) => a.name).join(", "),
+    album: i.track.album.name,
+    added_at: i.added_at,
+    uri: i.track.uri
+  }));
+  output(items, opts.json);
+}
+async function librarySaveCommand(opts) {
+  requireScopes(LIBRARY_WRITE_SCOPES);
+  const ids = opts.tracks.split(",").map((t) => t.trim().replace("spotify:track:", ""));
+  await spotify("/me/tracks", {
+    method: "PUT",
+    body: JSON.stringify({ ids })
+  });
+  console.log(`Saved ${ids.length} track(s) to library`);
+}
+async function libraryRemoveCommand(opts) {
+  requireScopes(LIBRARY_WRITE_SCOPES);
+  const ids = opts.tracks.split(",").map((t) => t.trim().replace("spotify:track:", ""));
+  await spotify("/me/tracks", {
+    method: "DELETE",
+    body: JSON.stringify({ ids })
+  });
+  console.log(`Removed ${ids.length} track(s) from library`);
+}
+async function libraryCheckCommand(opts) {
+  requireScopes(LIBRARY_READ_SCOPES);
+  const ids = opts.tracks.split(",").map((t) => t.trim().replace("spotify:track:", ""));
+  const data = await spotify(`/me/tracks/contains?ids=${ids.join(",")}`);
+  const items = ids.map((id, i) => ({
+    id,
+    saved: data[i]
+  }));
+  output(items, opts.json);
+}
+
 // src/commands/me.ts
 async function meCommand(opts) {
   const user = await spotify("/me");
@@ -305,6 +469,152 @@ async function meCommand(opts) {
   output(result, opts.json);
 }
 
+// src/commands/player.ts
+var PLAYER_SCOPES = [
+  "user-read-playback-state",
+  "user-modify-playback-state",
+  "user-read-currently-playing"
+];
+function handlePremiumError(err) {
+  if (err instanceof Error && err.message.includes("403")) {
+    console.error("Spotify Premium required for playback control.");
+    process.exit(1);
+  }
+  throw err;
+}
+async function playerNowCommand(opts) {
+  requireScopes(PLAYER_SCOPES);
+  const data = await spotify(
+    "/me/player/currently-playing"
+  );
+  if (!data || !("item" in data)) {
+    output({ playing: false }, opts.json);
+    return;
+  }
+  const result = {
+    playing: data.is_playing,
+    track: data.item.name,
+    artist: data.item.artists.map((a) => a.name).join(", "),
+    album: data.item.album.name,
+    progress_ms: data.progress_ms,
+    duration_ms: data.item.duration_ms,
+    device: data.device?.name,
+    shuffle: data.shuffle_state,
+    repeat: data.repeat_state,
+    uri: data.item.uri
+  };
+  output(result, opts.json);
+}
+async function playerPlayCommand(opts) {
+  requireScopes(PLAYER_SCOPES);
+  try {
+    const params = opts.device ? `?device_id=${opts.device}` : "";
+    const body = {};
+    if (opts.uri) {
+      if (opts.uri.includes(":track:")) {
+        body.uris = [opts.uri];
+      } else {
+        body.context_uri = opts.uri;
+      }
+    }
+    await spotify(`/me/player/play${params}`, {
+      method: "PUT",
+      body: Object.keys(body).length > 0 ? JSON.stringify(body) : void 0
+    });
+    console.log("Playing");
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerPauseCommand() {
+  requireScopes(PLAYER_SCOPES);
+  try {
+    await spotify("/me/player/pause", { method: "PUT" });
+    console.log("Paused");
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerNextCommand() {
+  requireScopes(PLAYER_SCOPES);
+  try {
+    await spotify("/me/player/next", { method: "POST" });
+    console.log("Skipped to next");
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerPrevCommand() {
+  requireScopes(PLAYER_SCOPES);
+  try {
+    await spotify("/me/player/previous", { method: "POST" });
+    console.log("Skipped to previous");
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerQueueCommand(uri) {
+  requireScopes(PLAYER_SCOPES);
+  const trackUri = uri.startsWith("spotify:") ? uri : `spotify:track:${uri}`;
+  try {
+    await spotify(`/me/player/queue?uri=${encodeURIComponent(trackUri)}`, {
+      method: "POST"
+    });
+    console.log(`Added to queue: ${trackUri}`);
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerDevicesCommand(opts) {
+  requireScopes(PLAYER_SCOPES);
+  const data = await spotify("/me/player/devices");
+  const items = data.devices.map((d) => ({
+    id: d.id,
+    name: d.name,
+    type: d.type,
+    active: d.is_active,
+    volume: d.volume_percent
+  }));
+  output(items, opts.json);
+}
+async function playerVolumeCommand(percent) {
+  requireScopes(PLAYER_SCOPES);
+  const vol = Number.parseInt(percent);
+  if (Number.isNaN(vol) || vol < 0 || vol > 100) {
+    console.error("Volume must be 0-100");
+    process.exit(1);
+  }
+  try {
+    await spotify(`/me/player/volume?volume_percent=${vol}`, { method: "PUT" });
+    console.log(`Volume: ${vol}%`);
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerShuffleCommand(state) {
+  requireScopes(PLAYER_SCOPES);
+  const enabled = state === "on" || state === "true";
+  try {
+    await spotify(`/me/player/shuffle?state=${enabled}`, { method: "PUT" });
+    console.log(`Shuffle: ${enabled ? "on" : "off"}`);
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+async function playerRepeatCommand(state) {
+  requireScopes(PLAYER_SCOPES);
+  if (!["off", "track", "context"].includes(state)) {
+    console.error("Repeat state must be: off, track, or context");
+    process.exit(1);
+  }
+  try {
+    await spotify(`/me/player/repeat?state=${state}`, { method: "PUT" });
+    console.log(`Repeat: ${state}`);
+  } catch (err) {
+    handlePremiumError(err);
+  }
+}
+
 // src/commands/playlist.ts
 async function playlistListCommand(opts) {
   const data = await spotify(
@@ -355,18 +665,18 @@ async function recommendCommand(opts) {
   }
   if (opts.seedArtists) {
     for (const artistId of opts.seedArtists.split(",")) {
-      const artist = await spotify(
+      const artist2 = await spotify(
         `/artists/${artistId.trim()}`
       );
-      queries.push(`artist:${artist.name}`);
+      queries.push(`artist:${artist2.name}`);
     }
   }
   if (opts.seedTracks) {
     for (const trackId of opts.seedTracks.split(",")) {
-      const track = await spotify(
+      const track2 = await spotify(
         `/tracks/${trackId.trim()}`
       );
-      queries.push(`artist:${track.artists[0].name}`);
+      queries.push(`artist:${track2.artists[0].name}`);
     }
   }
   if (queries.length === 0) {
@@ -434,14 +744,127 @@ async function searchCommand(query, opts) {
   }
 }
 
+// src/commands/top.ts
+var TOP_SCOPES = ["user-top-read"];
+async function topTracksCommand(opts) {
+  requireScopes(TOP_SCOPES);
+  const range = opts.range || "medium_term";
+  const limit = opts.limit || "20";
+  const data = await spotify(
+    `/me/top/tracks?time_range=${range}&limit=${limit}`
+  );
+  const items = data.items.map((t, i) => ({
+    rank: i + 1,
+    id: t.id,
+    name: t.name,
+    artist: t.artists.map((a) => a.name).join(", "),
+    album: t.album.name,
+    popularity: t.popularity,
+    uri: t.uri
+  }));
+  output(items, opts.json);
+}
+async function topArtistsCommand(opts) {
+  requireScopes(TOP_SCOPES);
+  const range = opts.range || "medium_term";
+  const limit = opts.limit || "20";
+  const data = await spotify(
+    `/me/top/artists?time_range=${range}&limit=${limit}`
+  );
+  const items = data.items.map((a, i) => ({
+    rank: i + 1,
+    id: a.id,
+    name: a.name,
+    genres: a.genres.join(", "),
+    popularity: a.popularity,
+    uri: a.uri
+  }));
+  output(items, opts.json);
+}
+
+// src/commands/track.ts
+var KEY_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+async function trackGetCommand(id, opts) {
+  const data = await spotify(`/tracks/${id}`);
+  const result = {
+    id: data.id,
+    name: data.name,
+    artist: data.artists.map((a) => a.name).join(", "),
+    album: data.album.name,
+    released: data.album.release_date,
+    duration_ms: data.duration_ms,
+    popularity: data.popularity,
+    explicit: data.explicit,
+    uri: data.uri,
+    url: data.external_urls.spotify
+  };
+  output(result, opts.json);
+}
+async function trackFeaturesCommand(id, opts) {
+  let data;
+  try {
+    data = await spotify(`/audio-features/${id}`);
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("403")) {
+      console.error("Audio features endpoint is restricted by Spotify. This may require an approved app.");
+      process.exit(1);
+    }
+    throw err;
+  }
+  const result = {
+    danceability: data.danceability,
+    energy: data.energy,
+    key: KEY_NAMES[data.key] ?? data.key,
+    mode: data.mode === 1 ? "major" : "minor",
+    loudness: data.loudness,
+    speechiness: data.speechiness,
+    acousticness: data.acousticness,
+    instrumentalness: data.instrumentalness,
+    liveness: data.liveness,
+    valence: data.valence,
+    tempo: Math.round(data.tempo),
+    time_signature: data.time_signature,
+    duration_ms: data.duration_ms
+  };
+  output(result, opts.json);
+}
+
 // src/index.ts
 var program = new Command();
-program.name("spoti-cli").description("Spotify Web API from your terminal").version("0.1.0");
-program.command("auth").description("Authenticate with Spotify (OAuth2 PKCE)").option("-c, --client-id <id>", "Spotify app client ID").action((opts) => authCommand(opts.clientId));
+program.name("spoti-cli").description("Spotify Web API from your terminal").version("0.2.0");
+program.command("auth").description("Authenticate with Spotify (OAuth2 PKCE)").option("-c, --client-id <id>", "Spotify app client ID").option("-u, --upgrade", "Re-authenticate with expanded permissions", false).action((opts) => authCommand(opts.clientId, opts.upgrade));
 program.command("search <query>").description("Search for tracks, artists, or albums").option("-t, --type <type>", "Search type: track, artist, album", "track").option("-l, --limit <n>", "Number of results", "10").option("--json", "Output as JSON", false).action((query, opts) => searchCommand(query, opts));
 program.command("recommend").description("Get track recommendations based on seeds").option("--seed-tracks <ids>", "Comma-separated track IDs").option("--seed-artists <ids>", "Comma-separated artist IDs").option("--seed-genres <genres>", "Comma-separated genres").option("-l, --limit <n>", "Number of recommendations", "20").option("--energy <n>", "Target energy (0.0-1.0)").option("--danceability <n>", "Target danceability (0.0-1.0)").option("--valence <n>", "Target valence/positiveness (0.0-1.0)").option("--tempo <n>", "Target tempo in BPM").option("--popularity <n>", "Target popularity (0-100)").option("--acousticness <n>", "Target acousticness (0.0-1.0)").option("--instrumentalness <n>", "Target instrumentalness (0.0-1.0)").option("--json", "Output as JSON", false).action((opts) => recommendCommand(opts));
 program.command("create <name>").description("Create a new playlist").option("-d, --description <text>", "Playlist description").option("--public", "Make playlist public", false).option("--tracks <uris>", "Comma-separated track URIs or IDs to add").option("-o, --open", "Open playlist in Spotify app after creation", false).option("--json", "Output as JSON", false).action((name, opts) => createCommand(name, opts));
 program.command("me").description("Show current user profile").option("--json", "Output as JSON", false).action((opts) => meCommand(opts));
+program.command("history").description("Recently played tracks").option("-l, --limit <n>", "Number of tracks (max 50)", "20").option("--json", "Output as JSON", false).action((opts) => historyCommand(opts));
+var player = program.command("player").description("Control playback");
+player.command("now").description("Show currently playing track").option("--json", "Output as JSON", false).action((opts) => playerNowCommand(opts));
+player.command("play").description("Start or resume playback").option("--uri <uri>", "Track, album, or playlist URI to play").option("--device <id>", "Device ID to play on").option("--json", "Output as JSON", false).action((opts) => playerPlayCommand(opts));
+player.command("pause").description("Pause playback").action(() => playerPauseCommand());
+player.command("next").description("Skip to next track").action(() => playerNextCommand());
+player.command("prev").description("Skip to previous track").action(() => playerPrevCommand());
+player.command("queue <uri>").description("Add a track to the queue").action((uri) => playerQueueCommand(uri));
+player.command("devices").description("List available devices").option("--json", "Output as JSON", false).action((opts) => playerDevicesCommand(opts));
+player.command("volume <percent>").description("Set volume (0-100)").action((percent) => playerVolumeCommand(percent));
+player.command("shuffle <state>").description("Toggle shuffle (on/off)").action((state) => playerShuffleCommand(state));
+player.command("repeat <state>").description("Set repeat mode (off/track/context)").action((state) => playerRepeatCommand(state));
+var top = program.command("top").description("Your top tracks and artists");
+top.command("tracks").description("Your most listened tracks").option("-r, --range <range>", "Time range: short_term, medium_term, long_term", "medium_term").option("-l, --limit <n>", "Number of results", "20").option("--json", "Output as JSON", false).action((opts) => topTracksCommand(opts));
+top.command("artists").description("Your most listened artists").option("-r, --range <range>", "Time range: short_term, medium_term, long_term", "medium_term").option("-l, --limit <n>", "Number of results", "20").option("--json", "Output as JSON", false).action((opts) => topArtistsCommand(opts));
+var library = program.command("library").description("Manage saved tracks");
+library.command("list").description("List saved tracks").option("-l, --limit <n>", "Number of tracks", "20").option("--offset <n>", "Offset for pagination", "0").option("--json", "Output as JSON", false).action((opts) => libraryListCommand(opts));
+library.command("save").description("Save tracks to library").requiredOption("--tracks <ids>", "Comma-separated track IDs or URIs").action((opts) => librarySaveCommand(opts));
+library.command("remove").description("Remove tracks from library").requiredOption("--tracks <ids>", "Comma-separated track IDs or URIs").action((opts) => libraryRemoveCommand(opts));
+library.command("check").description("Check if tracks are in library").requiredOption("--tracks <ids>", "Comma-separated track IDs or URIs").option("--json", "Output as JSON", false).action((opts) => libraryCheckCommand(opts));
+var track = program.command("track").description("Track details and audio features");
+track.command("get <id>").description("Get track details").option("--json", "Output as JSON", false).action((id, opts) => trackGetCommand(id, opts));
+track.command("features <id>").description("Get audio features (energy, danceability, tempo, key, etc.)").option("--json", "Output as JSON", false).action((id, opts) => trackFeaturesCommand(id, opts));
+var artist = program.command("artist").description("Artist details and discography");
+artist.command("get <id>").description("Get artist details").option("--json", "Output as JSON", false).action((id, opts) => artistGetCommand(id, opts));
+artist.command("top-tracks <id>").description("Get artist's top tracks").option("-m, --market <code>", "Market/country code", "US").option("--json", "Output as JSON", false).action((id, opts) => artistTopTracksCommand(id, opts));
+artist.command("albums <id>").description("Get artist's albums").option("-l, --limit <n>", "Number of albums", "20").option("--json", "Output as JSON", false).action((id, opts) => artistAlbumsCommand(id, opts));
+artist.command("related <id>").description("Get related artists").option("--json", "Output as JSON", false).action((id, opts) => artistRelatedCommand(id, opts));
 var playlist = program.command("playlist").description("Manage playlists");
 playlist.command("list").description("List your playlists").option("-l, --limit <n>", "Number of playlists", "20").option("--json", "Output as JSON", false).action((opts) => playlistListCommand(opts));
 playlist.command("get <id>").description("Get playlist details and tracks").option("--json", "Output as JSON", false).action((id, opts) => playlistGetCommand(id, opts));

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@crafter/spoti-cli",
-	"version": "0.1.1",
-	"description": "Spotify Web API from your terminal. Search, recommend, and create playlists.",
+	"version": "0.2.0",
+	"description": "Spotify Web API from your terminal. Search, playback, library, audio features, and playlists.",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {
@@ -30,7 +30,11 @@
 		"cli",
 		"playlist",
 		"music",
-		"terminal"
+		"terminal",
+		"playback",
+		"player",
+		"library",
+		"audio-features"
 	],
 	"license": "MIT",
 	"repository": {