Class: RSpotify::User

Inherits:
Base
  • Object
show all
Defined in:
lib/rspotify/user.rb

Instance Attribute Summary collapse

Attributes inherited from Base

#external_urls, #href, #id, #type, #uri

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#complete!, #method_missing, #respond_to?

Constructor Details

#initialize(options = {}) ⇒ User

Returns a new instance of User.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/rspotify/user.rb', line 69

def initialize(options = {})
  credentials = options['credentials']
  options     = options['info'] if options['info']

  @birthdate    ||= options['birthdate']
  @country      ||= options['country']
  @display_name ||= options['display_name']
  @email        ||= options['email']
  @followers    ||= options['followers']
  @images       ||= options['images']
  @product      ||= options['product']

  super(options)

  if credentials
    @@users_credentials ||= {}
    @@users_credentials[@id] = credentials
    @credentials = @@users_credentials[@id]
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class RSpotify::Base

Instance Attribute Details

#birthdate ⇒ String

The user’s date-of-birth. This field is only available when the current user has granted access to the user-read-birthdate scope.

Returns:

  • (String) —

    the current value of birthdate



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def birthdate
  @birthdate
end

#country ⇒ String

The country of the user, as set in the user’s account profile. An ISO 3166-1 alpha-2 country code. This field is only available when the current user has granted access to the user-read-private scope.

Returns:

  • (String) —

    the current value of country



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def country
  @country
end

#credentials ⇒ Hash

The credentials generated for the user with OAuth. Includes access token, token type, token expiration time and refresh token. This field is only available when the current user has granted access to any scope.

Returns:

  • (Hash) —

    the current value of credentials



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def credentials
  @credentials
end

#display_name ⇒ String

The name displayed on the user’s profile. This field is only available when the current user has granted access to the user-read-private scope.

Returns:

  • (String) —

    the current value of display_name



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def display_name
  @display_name
end

#email ⇒ String

The user’s email address. This field is only available when the current user has granted access to the user-read-email scope.

Returns:

  • (String) —

    the current value of email



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def email
  @email
end

#followers ⇒ Hash

Information about the followers of the user

Returns:

  • (Hash) —

    the current value of followers



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def followers
  @followers
end

#images ⇒ Array

The user’s profile image. This field is only available when the current user has granted access to the user-read-private scope.

Returns:

  • (Array) —

    the current value of images



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def images
  @images
end

#product ⇒ String

The user’s Spotify subscription level: “premium”, “free”, etc. This field is only available when the current user has granted access to the user-read-private scope.

Returns:

  • (String) —

    the current value of product



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def product
  @product
end

#tracks_added_at ⇒ Hash

A hash containing the date and time each track was saved by the user. Note: the hash is filled and updated only when #saved_tracks is used.

Returns:

  • (Hash) —

    the current value of tracks_added_at



12
13
14
 
# File 'lib/rspotify/user.rb', line 12

def tracks_added_at
  @tracks_added_at
end

Class Method Details

.find(id) ⇒ User

Returns User object with id provided

Examples:

user = RSpotify::User.find('wizzler')
user.class #=> RSpotify::User
user.id    #=> "wizzler"

Parameters:

  • id (String)

Returns:



23
24
25
 
# File 'lib/rspotify/user.rb', line 23

def self.find(id)
  super(id, 'user')
end

.oauth_send(user_id, verb, path, *params) ⇒ Object 



52
53
54
55
56
57
58
59
 
# File 'lib/rspotify/user.rb', line 52

def self.oauth_send(user_id, verb, path, *params)
  RSpotify.send(:send_request, verb, path, *params)
rescue RestClient::Unauthorized => e
  raise e if e.response !~ /access token expired/
  refresh_token(user_id)
  params[-1] = oauth_header(user_id)
  RSpotify.send(:send_request, verb, path, *params)
end

.search ⇒ Object

Spotify does not support search for users.



28
29
30
31
 
# File 'lib/rspotify/user.rb', line 28

def self.search(*)
  warn 'Spotify API does not support search for users'
  false
end

Instance Method Details

#create_playlist!(name, public: true) ⇒ Playlist

Creates a playlist in user’s Spotify account. This method is only available when the current user has granted access to the playlist-modify-public and playlist-modify-private scopes.

Examples:

user.create_playlist!('my-first-playlist')
user.playlists.last.name   #=> "my-first-playlist"
user.playlists.last.public #=> true

playlist = user.create_playlist!('my-second-playlist', public: false)
playlist.name   #=> "my-second-playlist"
playlist.public #=> false

Parameters:

  • name (String) —

    The name for the new playlist

  • public (Boolean) (defaults to: true) —

    Whether the playlist is public or private. Default: true

Returns:



105
106
107
108
109
110
111
112
 
# File 'lib/rspotify/user.rb', line 105

def create_playlist!(name, public: true)
  url = "users/#{@id}/playlists"
  request_data = { name: name, public: public }.to_json

  response = User.oauth_post(@id, url, request_data)
  return response if RSpotify.raw_response
  Playlist.new response
end

#follow(followed, public: true) ⇒ Artist, ...

Note:

Scopes you provide for playlists determine only whether the current user can themselves follow the playlist publicly or privately (i.e. show others what they are following), not whether the playlist itself is public or private.

Add the current user as a follower of one or more artists, other Spotify users or a playlist. Following artists or users require the user-follow-modify scope. Following a playlist publicly requires the playlist-modify-public scope; following it privately requires the playlist-modify-private scope.

Examples:

artists = RSpotify::Artist.search('John')
user.follow(artists)

playlist = RSpotify::Playlist.search('Movie').first
user.follow(playlist, public: false)

Parameters:

  • followed (Artist, Array<Artist>, User, Array<User>, Playlist) —

    The artists, users or playlist to follow

  • public (Boolean) (defaults to: true) —

    If true the playlist will be included in user’s public playlists, if false it will remain private.

Returns:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/rspotify/user.rb', line 129

def follow(followed, public: true)
  if followed.is_a? Array
    ids = followed.map(&:id).join(',')
    type = followed.first.type
  else
    ids = followed.id
    type = followed.type
  end

  if type == 'playlist'
    request_body = { public: public }
    url = "users/#{followed.owner.id}/playlists/#{followed.id}/followers"
  else
    request_body = {}
    url = "me/following?type=#{type}&ids=#{ids}"
  end

  User.oauth_put(@id, url, request_body.to_json)
  followed
end

#following(type: nil, limit: 20, after: nil) ⇒ Array<Artist>

Note:

The current Spotify API implementation only supports getting followed artists

Get the current user’s followed artists or users. Requires the user-follow-read scope.

Examples:

followed_artists = user.following(type: 'artist')
followed_artists.first.class #=> RSpotify::Artist

followed_artists = user.following(type: 'artist', limit: 50)

Parameters:

  • type (String) (defaults to: nil) —

    The ID type: currently only “artist” is supported

  • limit (Integer) (defaults to: 20) —

    Maximum number of items to return. Maximum: 50. Minimum: 1. Default: 20.

  • after (String) (defaults to: nil) —

    Optional. The last artist ID retrieved from the previous request.

Returns:



164
165
166
167
168
169
170
171
172
 
# File 'lib/rspotify/user.rb', line 164

def following(type: nil, limit: 20, after: nil)
  type_class = RSpotify.const_get(type.capitalize)
  url = "me/following?type=#{type}&limit=#{limit}"
  url << "&after=#{after}" if after

  response = User.oauth_get(@id, url)
  return response if RSpotify.raw_response
  response["#{type}s"]['items'].map { |i| type_class.new i }
end

#follows?(followed) ⇒ Array<Boolean>

Check if the current user is following one or more artists or other Spotify users. This method is only available when the current user has granted access to the user-follow-read scope.

Examples:

artists = RSpotify::Artist.search('John')
user.follows?(artists) #=> [true, false, true...]

Parameters:

Returns:

  • (Array<Boolean>) 


183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/rspotify/user.rb', line 183

def follows?(followed)
  if followed.is_a? Array
    ids = followed.map(&:id).join(',')
    type = followed.first.type
  else
    ids = followed.id
    type = followed.type
  end

  url = "me/following/contains?type=#{type}&ids=#{ids}"
  User.oauth_get(@id, url)
end

#playlists(limit: 20, offset: 0) ⇒ Array<Playlist>

Returns all playlists from user

Examples:

playlists = user.playlists
playlists.class       #=> Array
playlists.first.class #=> RSpotify::Playlist
playlists.first.name  #=> "Movie Soundtrack Masterpieces"

Parameters:

  • limit (Integer) (defaults to: 20) —

    Maximum number of playlists to return. Maximum: 50. Minimum: 1. Default: 20.

  • offset (Integer) (defaults to: 0) —

    The index of the first playlist to return. Use with limit to get the next set of playlists. Default: 0.

Returns:



207
208
209
210
211
212
 
# File 'lib/rspotify/user.rb', line 207

def playlists(limit: 20, offset: 0)
  url = "users/#{@id}/playlists?limit=#{limit}&offset=#{offset}"
  response = RSpotify.resolve_auth_request(@id, url)
  return response if RSpotify.raw_response
  response['items'].map { |i| Playlist.new i }
end

#remove_tracks!(tracks) ⇒ Array<Track>

Remove tracks from the user’s “Your Music” library.

Examples:

tracks = user.saved_tracks

user.saved_tracks.size #=> 20
user.remove_tracks!(tracks)
user.saved_tracks.size #=> 0

Parameters:

  • tracks (Array<Track>) —

    The tracks to remove. Maximum: 50.

Returns:

  • (Array<Track>) —

    The tracks removed.



225
226
227
228
229
230
 
# File 'lib/rspotify/user.rb', line 225

def remove_tracks!(tracks)
  tracks_ids = tracks.map(&:id)
  url = "me/tracks?ids=#{tracks_ids.join ','}"
  User.oauth_delete(@id, url)
  tracks
end

#save_tracks!(tracks) ⇒ Array<Track>

Save tracks to the user’s “Your Music” library.

Examples:

tracks = RSpotify::Track.search('Know')

user.saved_tracks.size #=> 0
user.save_tracks!(tracks)
user.saved_tracks.size #=> 20

Parameters:

  • tracks (Array<Track>) —

    The tracks to save. Maximum: 100.

Returns:

  • (Array<Track>) —

    The tracks saved.



243
244
245
246
247
248
249
 
# File 'lib/rspotify/user.rb', line 243

def save_tracks!(tracks)
  tracks_ids = tracks.map(&:id)
  url = "me/tracks"
  request_body = tracks_ids.inspect
  User.oauth_put(@id, url, request_body)
  tracks
end

#saved_tracks(limit: 20, offset: 0) ⇒ Array<Track>

Returns the tracks saved in the Spotify user’s “Your Music” library

Examples:

tracks = user.saved_tracks
tracks.size       #=> 20
tracks.first.name #=> "Do I Wanna Know?"

Parameters:

  • limit (Integer) (defaults to: 20) —

    Maximum number of tracks to return. Maximum: 50. Minimum: 1. Default: 20.

  • offset (Integer) (defaults to: 0) —

    The index of the first track to return. Use with limit to get the next set of tracks. Default: 0.

Returns:



261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/rspotify/user.rb', line 261

def saved_tracks(limit: 20, offset: 0)
  url = "me/tracks?limit=#{limit}&offset=#{offset}"
  response = User.oauth_get(@id, url)
  json = RSpotify.raw_response ? JSON.parse(response) : response

  tracks = json['items'].select { |i| i['track'] }
  @tracks_added_at = hash_for(tracks, 'added_at') do |added_at|
    Time.parse added_at
  end

  return response if RSpotify.raw_response
  tracks.map { |t| Track.new t['track'] }
end

#saved_tracks?(tracks) ⇒ Array<Boolean>

Check if tracks are already saved in the Spotify user’s “Your Music” library

Examples:

tracks = RSpotify::Track.search('Know')
user.saved_tracks?(tracks) #=> [true, false, true...]

Parameters:

  • tracks (Array<Track>) —

    The tracks to check. Maximum: 50.

Returns:

  • (Array<Boolean>) —

    Array of booleans, in the same order in which the tracks were specified.



283
284
285
286
287
 
# File 'lib/rspotify/user.rb', line 283

def saved_tracks?(tracks)
  tracks_ids = tracks.map(&:id)
  url = "me/tracks/contains?ids=#{tracks_ids.join ','}"
  User.oauth_get(@id, url)
end

#to_hash ⇒ Object

Returns a hash containing all user attributes



290
291
292
293
294
295
 
# File 'lib/rspotify/user.rb', line 290

def to_hash
  pairs = instance_variables.map do |var|
    [var.to_s.delete('@'), instance_variable_get(var)]
  end
  Hash[pairs]
end

#unfollow(unfollowed) ⇒ Artist, ...

Note:

Note that the scopes you provide for playlists relate only to whether the current user is following the playlist publicly or privately (i.e. showing others what they are following), not whether the playlist itself is public or private.

Remove the current user as a follower of one or more artists, other Spotify users or a playlist. Unfollowing artists or users require the user-follow-modify scope. Unfollowing a publicly followed playlist requires the playlist-modify-public scope; unfollowing a privately followed playlist requires the playlist-modify-private scope.

Examples:

artists = RSpotify::Artist.search('John')
user.unfollow(artists)

playlist = RSpotify::Playlist.search('Movie').first
user.unfollow(playlist)

Parameters:

Returns:



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/rspotify/user.rb', line 311

def unfollow(unfollowed)
  if unfollowed.is_a? Array
    ids = unfollowed.map(&:id).join(',')
    type = unfollowed.first.type
  else
    ids = unfollowed.id
    type = unfollowed.type
  end

  url = if type == 'playlist'
    "users/#{unfollowed.owner.id}/playlists/#{unfollowed.id}/followers"
  else
    "me/following?type=#{type}&ids=#{ids}"
  end

  User.oauth_delete(@id, url)
  unfollowed
end