refactor: Introduce SpotifyUri struct (#1538)

* refactor: Introduce SpotifyUri struct

Contributes to #1266

Introduces a new `SpotifyUri` struct which is layered on top of the
existing `SpotifyId`, but has the capability to support URIs that do
not confirm to the canonical base62 encoded format. This allows it to
describe URIs like `spotify:local`, `spotify:genre` and others that
`SpotifyId` cannot represent.

Changed the internal player state to use these URIs as much as possible,
such that the player could in the future accept a URI of the type
`spotify:local`, as a means of laying the groundwork for local file
support.

* fix: Don't pass unknown URIs from deprecated player methods

* refactor: remove SpotifyUri::to_base16

This should be deprecated for the same reason to_base62 is, and could unpredictably throw errors -- consumers should match on the inner ID if they need a base62 representation and handle failure appropriately

* refactor: Store original data in SpotifyUri::Unknown

Instead of assuming Unknown has a u128 SpotifyId, store the original data and type that we failed to parse.

* refactor: Remove SpotifyItemType

* refactor: Address review feedback

* test: Add more SpotifyUri tests

* chore: Correctly mark changes as breaking in CHANGELOG.md

* refactor: Respond to review feedback

* chore: Changelog updates

Author: SapiensAnatis

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) since v0.2.0.
 
+## [Unreleased]
+
+### Added
+
+- [core] Add `SpotifyUri` type to represent more types of URI than `SpotifyId` can
+
+### Changed
+
+- [playback] Changed type of `SpotifyId` fields in `PlayerEvent` members to `SpotifyUri` (breaking)
+- [metadata] Changed arguments for `Metadata` trait from `&SpotifyId` to `&SpotifyUri` (breaking)
+- [player] `load` function changed from accepting a `SpotifyId` to accepting a `SpotifyUri` (breaking)
+- [player] `preload` function changed from accepting a `SpotifyId` to accepting a `SpotifyUri` (breaking)
+- [spclient] `get_radio_for_track` function changed from accepting a `SpotifyId` to accepting a `SpotifyUri` (breaking)
+
+
+### Removed
+
+- [core] Removed `SpotifyItemType` enum; the new `SpotifyUri` is an enum over all item types and so which variant it is 
+  describes its item type (breaking)
+- [core] Removed `NamedSpotifyId` struct; it was made obsolete by `SpotifyUri` (breaking)
+- [core] The following methods have been removed from `SpotifyId` and moved to `SpotifyUri` (breaking):
+  - `is_playable`
+  - `from_uri`
+  - `to_uri`
+
 ## [v0.7.1] - 2025-08-31
 
 ### Changed

connect/src/spirc.rs

@@ -2,7 +2,7 @@ use crate::{
     LoadContextOptions, LoadRequestOptions, PlayContext,
     context_resolver::{ContextAction, ContextResolver, ResolveContext},
     core::{
-        Error, Session, SpotifyId,
+        Error, Session, SpotifyUri,
         authentication::Credentials,
         dealer::{
             manager::{BoxedStream, BoxedStreamResult, Reply, RequestReply},
@@ -778,7 +778,7 @@ impl SpircTask {
                 return Ok(());
             }
             PlayerEvent::Unavailable { track_id, .. } => {
-                self.handle_unavailable(track_id)?;
+                self.handle_unavailable(&track_id)?;
                 if self.connect_state.current_track(|t| &t.uri) == &track_id.to_uri()? {
                     self.handle_next(None)?
                 }
@@ -1499,7 +1499,7 @@ impl SpircTask {
     }
 
     // Mark unavailable tracks so we can skip them later
-    fn handle_unavailable(&mut self, track_id: SpotifyId) -> Result<(), Error> {
+    fn handle_unavailable(&mut self, track_id: &SpotifyUri) -> Result<(), Error> {
         self.connect_state.mark_unavailable(track_id)?;
         self.handle_preload_next_track();
 
@@ -1704,7 +1704,7 @@ impl SpircTask {
         }
 
         let current_uri = self.connect_state.current_track(|t| &t.uri);
-        let id = SpotifyId::from_uri(current_uri)?;
+        let id = SpotifyUri::from_uri(current_uri)?;
         self.player.load(id, start_playing, position_ms);
 
         self.connect_state

connect/src/state/context.rs

@@ -1,5 +1,5 @@
 use crate::{
-    core::{Error, SpotifyId},
+    core::{Error, SpotifyId, SpotifyUri},
     protocol::{
         context::Context,
         context_page::ContextPage,
@@ -449,8 +449,10 @@ impl ConnectState {
             (Some(uri), _) if uri.contains(['?', '%']) => {
                 Err(StateError::InvalidTrackUri(Some(uri.clone())))?
             }
-            (Some(uri), _) if !uri.is_empty() => SpotifyId::from_uri(uri)?,
-            (_, Some(gid)) if !gid.is_empty() => SpotifyId::from_raw(gid)?,
+            (Some(uri), _) if !uri.is_empty() => SpotifyUri::from_uri(uri)?,
+            (_, Some(gid)) if !gid.is_empty() => SpotifyUri::Track {
+                id: SpotifyId::from_raw(gid)?,
+            },
             _ => Err(StateError::InvalidTrackUri(None))?,
         };
 

connect/src/state/tracks.rs

@@ -1,5 +1,5 @@
 use crate::{
-    core::{Error, SpotifyId},
+    core::{Error, SpotifyUri},
     protocol::player::ProvidedTrack,
     state::{
         ConnectState, SPOTIFY_MAX_NEXT_TRACKS_SIZE, SPOTIFY_MAX_PREV_TRACKS_SIZE, StateError,
@@ -352,14 +352,14 @@ impl<'ct> ConnectState {
         Ok(())
     }
 
-    pub fn preview_next_track(&mut self) -> Option<SpotifyId> {
+    pub fn preview_next_track(&mut self) -> Option<SpotifyUri> {
         let next = if self.repeat_track() {
             self.current_track(|t| &t.uri)
         } else {
             &self.next_tracks().first()?.uri
         };
 
-        SpotifyId::from_uri(next).ok()
+        SpotifyUri::from_uri(next).ok()
     }
 
     pub fn has_next_tracks(&self, min: Option<usize>) -> bool {
@@ -381,7 +381,7 @@ impl<'ct> ConnectState {
         prev
     }
 
-    pub fn mark_unavailable(&mut self, id: SpotifyId) -> Result<(), Error> {
+    pub fn mark_unavailable(&mut self, id: &SpotifyUri) -> Result<(), Error> {
         let uri = id.to_uri()?;
 
         debug!("marking {uri} as unavailable");

core/src/lib.rs

@@ -32,6 +32,7 @@ mod socket;
 #[allow(dead_code)]
 pub mod spclient;
 pub mod spotify_id;
+pub mod spotify_uri;
 pub mod token;
 #[doc(hidden)]
 pub mod util;
@@ -42,3 +43,4 @@ pub use error::Error;
 pub use file_id::FileId;
 pub use session::Session;
 pub use spotify_id::SpotifyId;
+pub use spotify_uri::SpotifyUri;

core/src/spclient.rs

@@ -5,7 +5,7 @@ use std::{
 
 use crate::config::{OS, os_version};
 use crate::{
-    Error, FileId, SpotifyId,
+    Error, FileId, SpotifyId, SpotifyUri,
     apresolve::SocketAddress,
     config::SessionConfig,
     error::ErrorKind,
@@ -676,10 +676,10 @@ impl SpClient {
             .await
     }
 
-    pub async fn get_radio_for_track(&self, track_id: &SpotifyId) -> SpClientResult {
+    pub async fn get_radio_for_track(&self, track_uri: &SpotifyUri) -> SpClientResult {
         let endpoint = format!(
             "/inspiredby-mix/v2/seed_to_playlist/{}?response-format=json",
-            track_id.to_uri()?
+            track_uri.to_uri()?
         );
 
         self.request_as_json(&Method::GET, &endpoint, None, None)