napster 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0532d69a5aadf0f93bdef73a06c70612705f7843
-  data.tar.gz: 267c689350304c2cadfa9ab92df6e1237ed83c99
+  metadata.gz: 0f53597ca1c82bbe5dfdff89de0e2430077ff4c9
+  data.tar.gz: ac674709f442f4de9b040bad17ca6021766533c8
 SHA512:
-  metadata.gz: 52bcd887818637ee98a66af6976ec7edcca337fce2fdfb0b582706f5a81a01e4f211c13d8d570270fcd067e3172c923061e047b7155cb12848e2797cc119d460
-  data.tar.gz: 9abfbd14b16241c3e83929d6a4a669647b3fa8ab3e02899ef2484b7f6972334a8aa5d0404c10f709838dcd9558899fc9458ac2ecb7da54f1f51e3ae16c4f2285
+  metadata.gz: f7e5b49b0b9990cad7a882d29dfa086a9a9647622c930ae80c92ed6456f40950ec9d1ccfed09ec22c75037328c5b32652c0a89aa94ab1d3ab8e7b030e9086399
+  data.tar.gz: 5b7a4b1e5b93c1f727db9262c2a5ed10e7052500e3ccec7740ec9133fa1420229a9df487eaaa92736985acdefe22a788d31d118fc71766d63d7825efbefbb84b

data/.gitignore

@@ -1,9 +1,43 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
+*.gem
+*.lock
+*.rbc
+/.config
 /coverage/
-/doc/
+/InstalledFiles
 /pkg/
 /spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
 /tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+## Configs
+spec/config.yml
+
+## RBENV related
+.ruby-version

data/.rubocop.yml

@@ -0,0 +1,4 @@
+ClassLength:
+  Max: 300
+MethodLength:
+  Max: 20

data/README.md

@@ -1,8 +1,19 @@
-# Napster
+<!-- TODO: Move this SVG to Dev Portal assets when we have more assets.  Right now it's in Dropbox :) -->
+<a href="http://developer.napster.com/">
+  <img src="https://dl.dropboxusercontent.com/s/bfydqpzisetm7y3/napster.svg?dl=0" alt="Napster Logo" title="Napster API" align="right" width=150 height=150/>
+</a>
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/napster`. To experiment with that code, run `bin/console` for an interactive prompt.
+<!--
+Put Badges here when we have them:
+[![Build Status](https://travis-ci.org/)
+-->
+<!--
+TODO: Add this link to the top when we change name of Google Forum
+**Got a question?** Let us know via the Napster API [google forum](https://groups.google.com/forum/#!forum/rhapsody-api).
+-->
+# Napster Gem
 
-TODO: Delete this and the text above, and describe your gem
+A Ruby interface to the [Napster API](https://developer.napster.com/).
 
 ## Installation
 
@@ -20,22 +31,339 @@ Or install it yourself as:
 
     $ gem install napster
 
+### Ruby version
+
+Ruby version should be 2.0 or greater.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Setting up a client
+
+A **client** prepares you to make calls to Napster API.
+Here is an example code for setting up a client using
+[implicit method](https://developer.napster.com/api#authentication).
+
+``` ruby
+require 'napster'
+
+options = {
+  api_key: 'API_KEY',
+  api_secret: 'API_SECRET',
+}
+
+client = Napster::Client.new(options)
+```
+
+You can still set up a client with just an access token. However, you will
+not be able to refresh the access token and you won't be able to make any
+metadata calls. Only authenticated member calls will be allowed with this
+client.
+
+``` ruby
+options = { access_token: 'ACCESS_TOKEN' }
+client = Napster::Client.new(options)
+```
+
+### Getting an access token
+
+#### Password grant
+
+##### Method 1
+
+```ruby
+client_hash = {
+  api_key: 'API_KEY',
+  api_secret: 'API_SECRET',
+  username: 'USERNAME',
+  password: 'PASSWORD'
+}
+
+# Just by instantiating with api_key, api_secret, username, and password
+# you can authenticate by password_grant.
+client = Napster::Client.new(client_hash)
+
+client.authentication.access_token # => returns access_token
+client.authentication.refresh_token
+client.authentication.expires_in
+```
+
+##### Method 2
+
+```ruby
+client_hash = {
+  api_key: 'API_KEY',
+  api_secret: 'API_SECRET'
+}
+
+client = Napster::Client.new(client_hash)
+client.username = 'USERNAME'
+client.password = 'PASSWORD'
+client.connect
+
+client.authentication.access_token # => returns access_token
+client.authentication.refresh_token
+client.authentication.expires_in
+```
+
+#### OAuth 2
+
+```ruby
+client_hash = {
+  api_key: 'API_KEY',
+  api_secret: 'API_SECRET',
+  redirect_uri: 'REDIRECT_URI',
+  auth_code: 'AUTH_CODE'
+}
+
+client = Napster::Client.new(client_hash)
+client.connect
+
+client.authentication.access_token # => returns access_token
+client.authentication.refresh_token
+client.authentication.expires_in
+```
+
+### Refresh an access token
+
+Napster API's `access_token` expires in 24 hours after it is issued.
+You need to use the `refresh_token` to generate a new `access_token` when
+it is expired.
+
+*It is not recommended to get a new access_token - refresh_token
+through authentication after the old access_token expires.*
+
+```ruby
+client.refresh # => returns new access_token by refreshing it
+```
+
+### Making Requests
+
+#### Metadata API
+
+Metadata endpoints do not need the client to be authenticated.
+First, set up a client with `api_key` and `api_secret`.
+Then you can call metadata endpoints following this pattern.
+
+```ruby
+# takes a form of client.[resources].[method]
+
+# albums
+client.albums.new_releases(limit: 10)
+client.albums.staff_picks(limit: 10)
+client.albums.top(limit: 10)
+client.albums.find(artist_id) # => returns an album
+client.albums.find(artist_name) # => returns an album
+client.albums.find(artist_id).tracks(limit: 10) # => returns an album
+client.albums.find(artist_name).tracks(limit: 10) # => returns an album
+
+# artists
+client.artists.top(limit: 5)
+client.artists.find(artist_id) # => returns an artist
+client.artists.find(artist_name) # => returns an artist
+client.artists.find(artist_id).albums(offset: 5)
+client.artists.find(artist_id).new_albums(offset: 5)
+client.artists.find(artist_id).tracks(limit: 5)
+client.artists.find(artist_id).top_tracks(limit: 5)
+
+# favorites
+client.favorites.members_who_favorited_albums('Alb.5153820')
+client.favorites.members_who_favorited_artists('Art.954')
+client.favorites.member_favorites_for('Tra.5156528')
+
+# members
+client.members.playlists_for('D877082A5CBC5AC7E040960A390313EF', limit: 2)
+client.members.favorites_for('D877082A5CBC5AC7E040960A390313EF', limit: 2)
+client.members.favorite_playlists_for('D877082A5CBC5AC7E040960A390313EF', limit: 2)
+client.members.chart_for('D877082A5CBC5AC7E040960A390313EF', limit: 2)
+client.members.find('D877082A5CBC5AC7E040960A390313EF')
+client.members.find('dduda')
+client.members.screenname_available?('dduda')
+client.members.find('dduda').playlists(limit: 5)
+client.members.find('dduda').favorites(limit: 5)
+client.members.find('dduda').favorite_playlists(limit: 5)
+client.members.find('dduda').chart(limit: 5)
+
+# playlists
+client.playlists.playlists_of_the_day(limit: 3)
+client.playlists.featured(limit: 3)
+client.playlists.find('pp.125821370')
+client.playlists.find('pp.125821370').tracks(limit: 10)
+client.playlists.find('pp.125821370').tags
+
+# tags
+client.tags.all
+client.tags.find('tag.156763217')
+
+# tracks
+client.tracks.find('Tra.5156528')
+client.tracks.find_by_name('Marvins Room')
+```
+
+#### Authenticated Member API
+
+Authenticated member endpoints require the client to be authenticated.
+First, set up a client with `api_key` and `api_secret`.
+Authenticate the client by going through password grant method or
+OAuth2 method.
+Ensure that the client has access_token and refresh_token.
+Then you can call metadata endpoints following this pattern.
+
+```ruby
+# takes a form of client.me.[resources].[method]
+
+# favorites
+client.me.favorites.get(limit: 5)
+client.me.favorites.status(['Art.954', 'Alb.5153820', 'Tra.5156528'])
+client.me.favorites.add(['Art.954', 'Alb.5153820', 'Tra.5156528'])
+client.me.favorites.remove('Art.954')
+
+# followers
+client.me.followers.members(limit: 5)
+client.me.followers.by?(guids)
+
+# following
+client.me.following.members(limit: 5)
+client.me.following.by?(guids)
+client.me.following.follow(guids)
+client.me.following.unfollow(guids)
+
+# library
+client.me.library.artists(limit: 10)
+client.me.library.artist_albums('Art.954', limit: 10)
+client.me.library.artist_tracks('Art.954', limit: 10)
+client.me.library.albums(limit: 10)
+client.me.library.album_tracks('Alb.5153820', limit: 10)
+client.me.library.tracks(limit: 10)
+client.me.library.add_track(['Tra.5156528'])
+client.me.library.remove_track('Tra.5156528')
+client.me.library.last_updated_date
+
+# listening history
+client.me.listening_history(limit: 10)
+
+# playlists
+client.me.playlists.all(limit: 10)
+client.me.playlists.create({ 'name' => 'hiphop playlist' })
+client.me.playlists.find('mp.123123')
+client.me.playlists.update('mp.123123', { 'name' => 'hiphop playlist 2' })
+client.me.playlists.delete('mp.123123')
+client.me.playlists.set_private('mp.123123', 'public')
+client.me.playlists.set_private('mp.123123', 'private')
+client.me.playlists.add_tracks('mp.123123', ['Tra.5156528'])
+client.me.playlists.recommended_tracks('mp.123123')
+client.me.playlists.uploaded_images(id: 'mp.123123', size: 500) # id and size in px
+client.me.playlists.sourced_by('my_own_playlists',
+                               { artists: ['art.123', 'art.234'], tags: ['tag.123', 'tag.234'], guid: 'xyz', sort: 'alpha_asc', include_private: true, limit: 10, offset: 5})
+client.me.playlists.find('mp.123123').tracks(limit: 10)
+client.me.playlists.find('mp.123123').tags
+client.me.playlists.find('mp.123123').uploaded_images(500) # size in px
+
+# profile
+client.me.profile.get
+client.me.profile.update({ 'me' => { 'bio' => Faker::Lorem.word } })
+
+# tags
+client.me.tags.contents('favorite', '', {})
+```
+
+#### Query Parameters
+
+```ruby
+client.artists.top(limit: 5, offset: 5)
+```
+
+#### Request body for PUT / POST
+
+```ruby
+request_hash = {
+  body: {
+    name: 'name of the playlist',
+    tags: ['tag.1', 'tag.2'],
+    privacy: 'public',
+    tracks: ['tra.1', 'tra.2']
+  }
+}
+client.me.create_playlist(request_hash)
+```
+
+#### Error Handling
+
+Napster gem provides `ResponseError` which wraps response errors from Napster
+API. You can inspect error attributes as shown below.
+
+```ruby
+begin
+  client.playlists.find('pp.125821370').tracks({}) # problematic request
+rescue Exception => error
+  puts error.http_status # => 400
+  puts error.response_body
+    # => {"code":"BadRequestError","message":"limit query parameter is required"}
+  puts error.faraday_response.inspect
+    # => #<Faraday::Response:0x007fe9bc957150 @on_complete_callbacks=[], ...
+end
+```
+
+<!--
+### Versioning
+
+The Napster gem supports Napster API version 2.x and above only.
+When the client does not specify the version, it'll use the latest
+Napster API version.
+
+#### Versioned client
+
+You can set client to always use a specific version of Napster API.
+
+```ruby
+client.version = 'v2.1'
+client.artists.top # returns top artists using v2.1
+```
+
+#### Making one-off versioned request
+
+Even though the client already has a version set, you can still make
+one-off calls to a different version of Napster API.
+
+```ruby
+client.version = 'v2.1'
+client.v2_2.artists.top # returns top artists using v2.2
+client.artists.top # returns top artists using v2.1
+```
+-->
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Running tests
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Napster gem uses RSpec and FactoryGirl.
 
-## Contributing
+1. Get the API key and API secret from
+[Napster Developers site](https://developer.napster.com/).
+
+2. Create a file called `config.yml` in `spec` directory.
+
+3. Add the following with the correct API key and API secret
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/napster.
+``` yml
+config_variables:
+  API_KEY: 'API_KEY'
+  API_SECRET: 'API_SECRET'
+  USERNAME: 'USERNAME'
+  PASSWORD: 'PASSWORD'
+  REDIRECT_URI: 'REDIRECT_URI'
+```
+
+4. `$ bundle install`
+
+5. `$ rspec`
+
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/napster/napster-ruby.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+Napster and Napster logo are registered and unregistered trademarks of Rhapsody International in the United States and/or other countries. All company, product and service names used in this website are for identification purposes only.  All product names, logos, and brands are property of their respective owners.

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "napster"
+require 'bundler/setup'
+require 'napster'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "napster"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start