discogs-wrapper 1.1.4 → 2.0.0

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2010 Andrew Buntine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Based on a work at www.discogs.com.

data/README.markdown

@@ -1,11 +1,17 @@
 Discogs::Wrapper
 ================
 
+NOTE
+----
+  We are currently working on the next release of the API. It will implement all endpoints, pagination, have oAuth support, and use JSON exclusively.
+
+  Expecting to finish late-May, 2014.
+
 ABOUT
 -----
-  A 100% Ruby wrapper of the Discogs.com API. No dependencies, no extra gems. :)
+  A 100% Ruby wrapper of the Discogs.com API.
 
-  Discogs::Wrapper abstracts all the nasty boilerplate code needed to interact with the Discogs API. It gives you direct access to the information you need.
+  Discogs::Wrapper abstracts all of the boilerplate code needed to interact with the Discogs API. It gives you direct access to the information you need. All methods return a ruby Hash wrapped in a [Hashie](https://github.com/intridea/hashie) object with the same structure as documented on the [Discogs API website](http://www.discogs.com/developers/index.html).
 
   The master branch aims to give full support for version 2.0 of the API. If you need support for everything in version 1.0, see the api-v1 branch.
 
@@ -13,66 +19,140 @@ ABOUT
 
   * Artists
   * Releases
-  * MasterReleases
+  * Master Releases
   * Labels
+  * Images
   * Searching (all of the above)
+  * Marketplace
+  * User Inventories
+  * Orders
+  * Fee Calculations
+  * Price Suggestions
+  * User Profiles
+  * Collections
+  * Wantlists
+  * oAuth
+  * Pagination / Sorting
 
-  Please, [see the Wiki](http://github.com/buntine/discogs/wiki) for helpful documentation.
 
-  The Discogs API is [documented here](http://www.discogs.com/help/api).
+  The Discogs API is [documented here](http://www.discogs.com/developers/index.html).
+
+  You can see all implemented methods on [this projects RDoc page](http://rdoc.info/github/buntine/discogs/master/frames).
 
 INSTALLATION
 ------------
   You can install the library via Rubygems:
 
-    $ sudo gem install discogs-wrapper
+    $ gem install discogs-wrapper
+
+  Or within your Gemfile:
+
+    gem "discogs-wrapper"
 
 USAGE
 -----
   To use this library, you must supply the name of your application. For example:
 
-    require 'discogs'
     wrapper = Discogs::Wrapper.new("My awesome web app")
 
   Accessing information is easy:
 
-    artist = wrapper.get_artist("Master's Hammer")
-    release = wrapper.get_release("611973") # Supply an ID.
-    label = wrapper.get_label("Monitor Records")
-    search = wrapper.search("Necrovore")
-
-    artist.name                         # => "Master's Hammer"
-    artist.releases[0].title            # => "Finished"
-    artist.releases[1].year             # => "1989"
-    artist.releases[4].extraartists     # => [ "Arakain", "Debustrol" ]
-
-    release.title                       # => "Ritual"
-    release.labels[0].name              # => "Osmose Productions"
-    release.formats[0].descriptions[0]  # => "LP"
-    release.styles                      # => [ "Black Metal", "Death Metal" ]
-    release.tracklist[1].title          # => "Pad modly"
-
-    label.images[0].width               # => "220"
-    label.releases.length               # => 22
-    label.releases[3].artist            # => "Root"
-    label.releases[7].catno             # => "MON007"
-
-    search.total_results                # => 124
-    search.total_pages                  # => 7
-    search.current_page                 # => 1
-
-    # Exact results
-    search.exact[0].type                # => "artist"
-    search.exact[0].title               # => "Necrovore"
-    search.exact(:label)[0].title       # => "Necrovores Records"
-    search.closest(:artist)             # => <Discogs::Search::Result:0x324ad3e2>
-
-    # All results
-    search.results[3].title             # => "Necrovore - Demo '87"
-    search.results[3].summary           # => "First and only demo tape"
-    search.results(:release)[0]         # => <Discogs::Search::Result:0x343de34a>
+    artist          = wrapper.get_artist("329937")
+    artist_releases = wrapper.get_artist_releases("329937")
+    release         = wrapper.get_release("1529724")
+    label           = wrapper.get_label("29515")
+    search          = wrapper.search("Necrovore", :per_page => 10, :type => :artist)
+
+    artist.name                          # => "Manilla Road"
+    artist.members.count                 # => 4
+    artist.members.first.name            # => "Mark Shelton"
+    artist.profile                       # => "Heavy Metal band from ..."
+
+    artist_releases.releases.count       # => 35
+    artist_releases.releases.first.title # => "Invasion"
+
+    release.title                        # => "Medieval"
+    release.labels.first.name            # => "New Renaissance Records"
+    release.formats[0].descriptions[0]   # => "12\""
+    release.styles                       # => [ "Heavy Metal", "Doom Metal" ]
+    release.tracklist[1].title           # => "Death is Beauty"
+
+    label.name                           # => "Monitor (2)"
+    label.sublabels.count                # => 3
+
+    search.pagination.items              # => 2
+    search.results.first.title           # => "Necrovore"
+    search.results.first.type            # => "artist"
+    search.results.first.id              # => 691078
+
+  Many of the API endpoints return further URLs that will yield specific data. To cater for this, the library provides a "raw" method that accepts a valid API URL. For example:
+
+    sts_records       = wrapper.get_label(9800)
+    sts_releases      = wrapper.raw(sts_records.releases_url)
+    first_sts_release = wrapper.raw(sts_releases.releases[1].resource_url)
+
+    first_sts_release.title  # => "I'll Nostra Tempo De La Vita / Having The Time Of Your Life"
+
+  You can see all implemented methods on [this projects RDoc page](http://rdoc.info/github/buntine/discogs/master/frames).
+
+AUTHENTICATION
+--------------
+  Many of the API endpoints require the user to be authenticated via oAuth. The library provides support for this.
+
+  I've provided [https://github.com/buntine/discogs-oauth](a simple Rails application) that demonstrates how to perform authenticated requests.
+
+  Make sure you've created an "app" in your developer settings on the Discogs website. You will need your consumer key and consumer secret.
+
+  Basically, you should preform the "oAuth dance" like so:
+
+    # Add an action to initiate the process.
+    def authenticate
+      @discogs     = Discogs::Wrapper.new("Test OAuth")
+      request_data = @discogs.get_request_token("YOUR_APP_KEY", "YOUR_APP_SECRET", "http://127.0.0.1:3000/callback")
+
+      session[:request_token] = request_data[:request_token]
+
+      redirect_to request_data[:authorize_url]
+    end
+
+    # And an action that Discogs will redirect back to.
+    def callback
+      @discogs      = Discogs::Wrapper.new("Test OAuth")
+      request_token = session[:request_token]
+      verifier      = params[:oauth_verifier]
+      access_token  = @discogs.authenticate(request_token, verifier)
+
+      session[:request_token] = nil
+      session[:access_token]  = access_token
+
+      @discogs.access_token = access_token
+
+      # You can now perform authenticated requests.
+    end
+
+    # Once you have it, you can also pass your access_token into the constructor.
+    def another_action
+      @discogs = Discogs::Wrapper.new("Test OAuth", session[:access_token])
+
+      # You can now perform authenticated requests.
+    end
+
+PAGINATION
+----------
+  All API endpoints that accept pagination, sorting or other parameters are supported.
+ 
+  Page defaults to 1, page size defaults to 50.
+
+    wrapper.get_artist_releases(345211, :page => 2, :per_page => 10)
+
+  If other params are accepted, they can also be passed:
+
+    wrapper.get_user_inventory("username", :page => 3, :sort => "price", :sort_order => "asc")
 
 LICENSE
 -----
+  See the LICENCE file. Copyright (c) Andrew Buntine
 
-See the LICENCE file. Copyright (c) Andrew Buntine
+CONTRIBUTORS
+------------
+  List all contributors.

data/lib/discogs-wrapper.rb

@@ -0,0 +1 @@
+require 'discogs'

data/lib/discogs.rb

@@ -15,6 +15,7 @@ module Discogs; end
 # Custom exceptions.
 class Discogs::UnknownResource < Exception; end
 class Discogs::InternalServerError < Exception; end
+class Discogs::AuthenticationError < Exception; end
 
 # Loading sequence.
 require File.dirname(__FILE__) + "/wrapper/wrapper"

data/lib/wrapper/authentication.rb

@@ -0,0 +1,56 @@
+require 'oauth'
+
+module Authentication
+
+  # Retrieves an OAuth request token from the Discogs server.
+  # @!macro [new] app_key
+  # @!macro [new] app_secret
+  #   @param app_key [String] application id
+  #   @param app_secret [String] application secret
+  # @return [Hash] containing a :request_token that should be stored locally and a :authorize_url that the user must browse to.
+  def get_request_token(app_key, app_secret, callback)
+    consumer      = OAuth::Consumer.new(app_key, app_secret,
+                      :authorize_url => "http://www.discogs.com/oauth/authorize",
+                      :site          => "http://api.discogs.com")
+    request_token = consumer.get_request_token(:oauth_callback => callback)
+
+    {:request_token => request_token,
+     :authorize_url => request_token.authorize_url(:oauth_callback => callback)}
+  end
+
+  # Retrieves an OAuth access token from the Discogs server.
+  # @!macro [new] request_token
+  # @!macro [new] verifier
+  #   @param request_token [OAuth::RequestToken] request token
+  #   @param verifier [String] verifier token
+  # @return [OAuth::AccessToken] 
+  def authenticate(request_token, verifier)
+    @access_token = request_token.get_access_token(:oauth_verifier => verifier)
+  end
+
+  # Returns true if an OAuth access_token is present. If a username is given, the authenticated username must match it.
+  # @!macro [new] username
+  #   @param username [String] username
+  # @return [Boolean]
+  def authenticated?(username=nil, &block)
+    auth = if username
+      @access_token and authenticated_username == username
+    else
+      !!@access_token
+    end
+
+    if block_given?
+      auth ? yield : raise_authentication_error
+    else
+      auth
+    end
+  end
+
+ private
+
+  def authenticated_username
+    data = get_identity
+    data.username
+  end
+
+end

data/lib/wrapper/wrapper.rb

@@ -1,114 +1,803 @@
 # Core API wrapper class.
 
-require 'uri'
+require 'hashie'
+require 'json'
 require 'net/http'
-require 'rexml/document'
-require 'zlib'
 require 'stringio'
+require 'uri'
+require 'cgi'
+require 'zlib'
 
-require File.dirname(__FILE__) + "/resource"
+require File.dirname(__FILE__) + "/authentication"
 
 class Discogs::Wrapper
 
+  include Authentication
+
   @@root_host = "http://api.discogs.com"
 
   attr_reader :app_name
+  attr_accessor :access_token
+
+  def initialize(app_name, access_token=nil)
+    @app_name     = app_name
+    @access_token = access_token
+  end
 
-  def initialize(app_name=nil)
-    @app_name = app_name
+  # Retrieves a release by ID.
+  # @!macro [new] release_id
+  #   @param release_id [Integer] release id
+  # @return [Hash] the release with provided release_id
+  def get_release(release_id)
+    query_and_build "releases/#{release_id}"
   end
 
-  def get_release(id)
-    query_and_build "release/#{id}", Discogs::Release
+  # Retrieves a master release by ID.
+  # @!macro [new] master_release_id
+  #   @param master_release_id [Integer] master release id
+  # @return [Hash] the master release with provided master_release_id
+  def get_master_release(master_release_id)
+    query_and_build "masters/#{master_release_id}"
   end
 
-  def get_master_release(id)
-    query_and_build "master/#{id}", Discogs::MasterRelease
+  alias_method :get_master, :get_master_release
+
+  # Retrieves a list of all Releases that are versions of this master. Accepts Pagination parameters.
+  # @macro master_release_id
+  # @!macro [new] uses_pagination
+  #   @param pagination [Hash] pagination parameters
+  # @return [Hash] the master release with the provided master_release_id, along with versions
+  def get_master_release_versions(master_release_id, pagination={})
+    query_and_build "masters/#{master_release_id}/versions", pagination
   end
 
-  def get_artist(name)
-    query_and_build "artist/#{name}", Discogs::Artist, {:releases => 1}
+  # Retrieves an artist by ID.
+  # @!macro [new] artist_id
+  #   @param artist_id [Integer] artist id
+  # @return [Hash] the artist with provided artist_id
+  def get_artist(artist_id)
+    query_and_build "artists/#{artist_id}"
   end
 
-  def get_label(name)
-    query_and_build "label/#{name}", Discogs::Label, {:releases => 1}
+  # Returns a list of Releases and Masters associated with the artist. Accepts Pagination parameters.
+  # @macro artist_id
+  # @macro uses_pagination
+  # @return [Hash] the releases for artist with provided artist_id
+  def get_artists_releases(artist_id, pagination={})
+    query_and_build "artists/#{artist_id}/releases", pagination
   end
 
+  alias_method :get_artist_releases, :get_artists_releases
+
+  # Retrieves a label by ID.
+  # @!macro [new] label_id
+  #   @param label_id [Integer] label id
+  # @return [Hash] the label with provided id
+  def get_label(label_id)
+    query_and_build "labels/#{label_id}"
+  end
+
+  # Returns a list of Releases associated with the label. Accepts Pagination parameters.
+  # @macro label_id
+  # @macro uses_pagination
+  # @return [Hash] the releases for label with provided id
+  def get_labels_releases(label_id, pagination={})
+    query_and_build "labels/#{label_id}/releases", pagination
+  end
+
+  alias_method :get_label_releases, :get_labels_releases
+
+  # Retrieve a user by username.
+  #
+  # If authenticated as the requested user, the email key will be visible.
+  #
+  # If authenticated as the requested user or the user’s collection/wantlist is public,
+  # the num_collection / num_wantlist keys will be visible.
+  #
+  # @!macro [new] username
+  #   @param username [String] username
+  # @return [Hash] the user with provided username
   def get_user(username)
-    query_and_build "users/#{username}", Discogs::User
+    query_and_build "users/#{username}"
+  end
+
+  # Get a collection for a user by username
+  #
+  # Shortcut method for #get_user_folder_releases[#get_user_folder_releases-instance_method]
+  #
+  # @macro username
+  # @macro uses_pagination
+  # @return [Hash] the user with provided username
+  def get_user_collection(username, pagination={})
+    get_user_folder_releases(username, 0)
+  end
+
+  # Retrieve a list of user-defined collection notes fields. These fields are available on every release in the collection.
+  #
+  # If the collection has been made private by its owner, authentication as the collection owner is required.
+  #
+  # If you are not authenticated as the collection owner, only fields with public set to true will be visible.
+  #
+  # @macro username
+  # @return [Hash] list of collection fields for the provided username
+  def get_user_collection_fields(username)
+    query_and_build "users/#{username}/collection/fields"
+  end
+
+  # Returns the list of releases in a user’s wantlist. Accepts Pagination parameters.
+  #
+  # Basic information about each release is provided, suitable for display in a list. For detailed information, make another API call to fetch the corresponding release.
+  #
+  # If the wantlist has been made private by its owner, you must be authenticated as the owner to view it.
+  #
+  # The notes field will be visible if you are authenticated as the wantlist owner.
+  #
+  # @macro username
+  # @macro uses_pagination
+  # @return [Hash] wantlist for the provided username
+  def get_user_wantlist(username, pagination={})
+    query_and_build "users/#{username}/wants", pagination
+  end
+
+  alias_method :get_user_wants, :get_user_wantlist
+
+  # Returns a specific release in a user’s wantlist by release id.
+  #
+  # If the wantlist has been made private by its owner, you must be authenticated as the owner to view it.
+  #
+  # The notes field will be visible if you are authenticated as the wantlist owner.
+  #
+  # @macro username
+  # @macro release_id
+  # @return [Hash] wantlist for the provided username
+  def get_user_want(username, release_id)
+    query_and_build "users/#{username}/wants/#{release_id}"
+  end
+
+  # Add a release to a user’s wantlist.
+  #
+  # @!macro [new] need_auth
+  #   @note Authentication as the owner is required.
+  #
+  # @macro username
+  # @macro release_id
+  # @param [Hash] data optional parameters:
+  # @option data [String] :notes User notes to associate with this release.
+  # @option data [Integer] :rating User’s rating of this release, from 0 (unrated) to 5 (best). Defaults to 0.
+  # @return [Hash] new wantlist entry
+  def add_release_to_user_wantlist(username, release_id, data={})
+    authenticated? do
+      query_and_build "users/#{username}/wants/#{release_id}", {}, :put, data
+    end
+  end
+
+  # Edit the notes (or rating) on a release in a user’s wantlist.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro release_id
+  # @param data [Hash] optional parameters:
+  # @option data [String] :notes User notes to associate with this release.
+  # @option data [Integer] :rating User’s rating of this release, from 0 (unrated) to 5 (best). Defaults to 0.
+  # @return [Hash] updated wantlist entry
+  def edit_release_in_user_wantlist(username, release_id, data={})
+    authenticated? do
+      query_and_build "users/#{username}/wants/#{release_id}", {}, :post, data
+    end
+  end
+
+  # Remove a release from a user's wantlist.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro release_id
+  # @return [Boolean]
+  def delete_release_in_user_wantlist(username, release_id)
+    authenticated? do
+      query_and_build "users/#{username}/wants/#{release_id}", {}, :delete
+    end
+  end
+
+  alias_method :delete_release_from_user_wantlist, :delete_release_in_user_wantlist
+
+  # Retrieve basic information about the authenticated user.
+  #
+  # You can use this resource to find out who you’re authenticated as, and it also doubles as a good sanity check to ensure that you’re using OAuth correctly.
+  #
+  # For more detailed information, make another request for the user’s Profile.
+  #
+  # @macro need_auth
+  # @return [Hash] authenticated user information
+  def get_identity
+    authenticated? do
+      query_and_build "oauth/identity"
+    end
+  end
+
+  # Edit a user’s profile data.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @param [Hash] data data to update, with the optional keys:
+  # @option data [String] :name The real name of the user.
+  # @option data [String] :home_page The user's website.
+  # @option data [String] :location The geographical location of the user.
+  # @option data [String] :profile Biographical information about the user.
+  def edit_user(username, data={})
+    authenticated? do
+      query_and_build "users/#{username}", {}, :post, data
+    end
+  end
+
+  # Add a release to a folder in a user’s collection.
+  #
+  # @macro need_auth
+  #
+  # The folder_id must be non-zero – you can use 1 for “Uncategorized”.
+  #
+  # @macro username
+  # @!macro [new] folder_id
+  #   @param folder_id [Integer] folder id
+  # @macro release_id
+  # @return [Hash] new instance metadata
+  def add_release_to_user_folder(username, folder_id, release_id)
+    authenticated? do
+      query_and_build "users/#{username}/collection/folders/#{folder_id}/releases/#{release_id}", {}, :post
+    end
+  end
+
+  alias_method :add_instance_to_user_folder, :add_release_to_user_folder
+
+  # Change the rating on a release and/or move the instance to another folder.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @macro release_id
+  # @!macro [new] instance_id
+  #   @param instance_id [Integer] instance id
+  # @param [Hash] data optional parameters
+  # @option data [Integer] :rating User’s rating of this release, from 0 (unrated) to 5 (best).
+  # @option data [Integer] :folder_id The ID of the folder to move the release into.
+  # @return [Boolean]
+  def edit_release_in_user_folder(username, folder_id, release_id, instance_id=1, data={})
+    authenticated? do
+      query_and_build "/users/#{username}/collection/folders/#{folder_id}/releases/#{release_id}/instances/#{instance_id}"
+    end
+  end
+
+  alias_method :edit_instance_in_user_folder, :edit_release_in_user_folder
+
+  # Remove an instance of a release from a user’s collection folder.
+  #
+  # To move the release to the “Uncategorized” folder instead, use the POST method.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @macro release_id
+  # @macro instance_id
+  # @return [Boolean]
+  def delete_instance_in_user_folder(username, folder_id, release_id, instance_id)
+    authenticated? do
+      query_and_build "/users/#{username}/collection/folders/#{folder_id}/releases/#{release_id}/instances/#{instance_id}", {},  :delete
+    end
+  end
+
+  alias_method :delete_release_in_user_folder, :delete_instance_in_user_folder
+
+  # Change the value of a notes field on a particular instance.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @macro release_id
+  # @macro instance_id
+  # @!macro [new] field_id
+  #   @param field_id [Integer] field id
+  # @option data [String] :value The new value of the field. If the field’s type is dropdown, the value must match one of the values in the field’s list of options.
+  def edit_field_on_instance_in_user_folder(username, folder_id, release_id, instance_id, field_id, data={})
+    authenticated? do
+      query_and_build "/users/#{username}/collection/folders/#{folder_id}/releases/#{release_id}/instances/#{instance_id}/fields/#{field_id}", {}, :post, data
+    end
+  end
+
+  # Returns the list of releases in a folder in a user’s collection. Accepts Pagination parameters.
+  #
+  # Basic information about each release is provided, suitable for display in a list. For detailed information, make another API call to fetch the corresponding release.
+  #
+  # If folder_id is not 0, or the collection has been made private by its owner, authentication as the collection owner is required.
+  #
+  # If you are not authenticated as the collection owner, only public notes fields will be visible.
+  #
+  # @macro username
+  # @macro folder_id
+  # @param [Hash] params optional parameters
+  # @option params [String] :sort Sort items by this field. One of:
+  #   * +label+
+  #   * +artist+
+  #   * +title+
+  #   * +catno+
+  #   * +format+
+  #   * +rating+
+  #   * +added+
+  #   * +year+
+  # @option params [String] :sort_order Sort items in a particular order. One of:
+  #   * +asc+
+  #   * +desc+
+  def get_user_folder_releases(username, folder_id, params={})
+    if folder_id == 0 or authenticated?
+      query_and_build "users/#{username}/collection/folders/#{folder_id}/releases", params
+    else
+      raise_authentication_error
+    end
+  end
+
+  # Retrieve metadata about a folder in a user’s collection.
+  #
+  # If folder_id is not 0, authentication as the collection owner is required.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @return [Hash] folder with folder_id
+  def get_user_folder(username, folder_id)
+    if folder_id == 0 or authenticated?
+      query_and_build "users/#{username}/collection/folders/#{folder_id}"
+    else
+      raise_authentication_error
+    end
   end
 
-  def search(term, options={})
-    opts = { :type => :all, :page => 1 }.merge(options)
-    params = { :q => term, :type => opts[:type], :page => opts[:page] }
+  # Retrieve a list of folders in a user’s collection.
+  #
+  # If the collection has been made private by its owner, authentication as the collection owner is required.
+  #
+  # If you are not authenticated as the collection owner, only folder ID 0 (the “All” folder) will be visible.
+  #
+  # @macro username
+  # @return [Hash] folder listing
+  def get_user_folders(username)
+    query_and_build "users/#{username}/collection/folders"
+  end
+
+  # Create a new folder in a user’s collection.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @param [Hash] data folder parameters
+  # @option data [String] :name The name of the newly-created folder (Required).
+  # @return [Hash] new folder metadata
+  def create_user_folder(username, data={})
+    authenticated? do
+      query_and_build "users/#{username}/collection/folders", {}, :post, data
+    end
+  end
+
+  alias_method :add_user_folder, :create_user_folder
+
+  # Edit a folder’s metadata. Folders 0 and 1 cannot be renamed.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @param [Hash] data folder parameters
+  # @option data [String] :name The name of the folder (Required).
+  # @return [Hash] updated folder metadata
+  def edit_user_folder(username, folder_id, data={})
+    authenticated? do
+      query_and_build "users/#{username}/collection/folders#{folder_id}", {}, :post, data
+    end
+  end
+
+  # Delete a folder from a user’s collection. A folder must be empty before it can be deleted.
+  #
+  # @macro need_auth
+  #
+  # @macro username
+  # @macro folder_id
+  # @return [Boolean]
+  def delete_user_folder(username, folder_id)
+    authenticated? do
+      query_and_build "users/#{username}/collection/folders#{folder_id}", {}, :delete
+    end
+  end
+
+  # Returns the list of listings in a user’s inventory. Accepts Pagination parameters.
+  #
+  # Basic information about each listing and the corresponding release is provided, suitable for display in a list. For detailed information about the release, make another API call to fetch the corresponding Release.
+  #
+  # If you are not authenticated as the inventory owner, only items that have a status of For Sale will be visible.
+  #
+  # If you are authenticated as the inventory owner you will get additional +weight+, +format_quantity+, and +external_id+ keys.
+  #
+  # @macro username
+  # @param [Hash] params sort/order/pagination parameters
+  # @option params [String] :status Only show items with this status
+  # @option params [String] :sort Sort items by this field. One of:
+  #   * +listed+
+  #   * +price+
+  #   * +item+ (i.e. the title of the release)
+  #   * +artist+
+  #   * +label+
+  #   * +catno+
+  #   * +audio+
+  #   * +status+ (when authenticated as inventory owner)
+  # @option params [String] :sort_order Sort items in a particular order. One of:
+  #   * +asc+
+  #   * +desc+
+  # @return [Hash] listing in user's inventory
+  def get_user_inventory(username, params={})
+    query_and_build "users/#{username}/inventory", params
+  end
+
+  # View the data associated with a listing.
+  #
+  # If the authorized user is the listing owner the listing will include the +weight+, +format_quantity+, and +external_id+ keys.
+  #
+  # @!macro [new] listing_id
+  #   @param listing_id [Integer] listing id
+  # @return [Hash] listing with listing_id
+  def get_listing(listing_id)
+    query_and_build "marketplace/listings/#{listing_id}"
+  end
+
+  # Create a Marketplace listing.
+  #
+  # @macro need_auth
+  #
+  # @!macro [new] listing_params
+  #   @param [Hash] data parameters for listing
+  #   @option data [Integer (Required)] :release_id The ID of the release that this listing represents.
+  #   @option data [String (Optional)] :condition The physical condition of the item. Must *EXACTLY* match one of:
+  #     * +Mint (M)+
+  #     * +Near Mint (NM or NM-)+
+  #     * +Very Good Plus (VG+)+
+  #     * +Very Good (VG)+
+  #     * +Good Plus (G+)+
+  #     * +Good (G)+
+  #     * +Fair (F)+
+  #     * +Poor (P)+
+  #   @option data [String (Optional)] :sleeve_condition (+Not Graded+) The physical condition of the item's sleeve, case, or container. Must *EXACTLY* match one of:
+  #     * +Mint (M)+
+  #     * +Near Mint (NM or NM-)+
+  #     * +Very Good Plus (VG+)+
+  #     * +Very Good (VG)+
+  #     * +Good Plus (G+)+
+  #     * +Good (G)+
+  #     * +Fair (F)+
+  #     * +Poor (P)+
+  #     * +Generic+
+  #     * +Not Graded+
+  #     * +No Cover+
+  #   @option data [Float (Required)] :price The price of the item (in the seller's currency).
+  #   @option data [String (Optional)] :comments Any remarks about the item that will be displayed to buyers.
+  #   @option data [Boolean (Optional)] :allow_buffers (false) Whether or not to allow buyers to make offers on the item. Defaults to +false+.
+  #   @option data [String (Optional)] :status (+For Sale+) The status of the listing. Defaults to For Sale. Must *EXACTLY* match one of:
+  #     * +For Sale+ - the listing is ready to be shown on the Marketplace
+  #     * +Draft+ - the listing is not ready for public display
+  #   @option data [String (Optional)] :external_id  A freeform field that can be used for the seller’s own reference. Information stored here will not be displayed to anyone other than the seller. This field is called “Private Comments” on the Discogs website.
+  #   @option data [Float (Optional)] :weight The weight, in grams, of this listing, for the purpose of calculating shipping.
+  #   @option data [Integer (Optional)] :format_quantity The number of items this listing counts as, for the purpose of calculating shipping. This field is called “Counts As” on the Discogs website.
+  #   @return [Hash] listing metadata
+  def create_listing(data={})
+    authenticated? do
+      query_and_build "marketplace/listings", {}, :post, data
+    end
+  end
+
+  # Edit the data associated with a listing.
+  #
+  # If the listing’s status is not +For Sale+, +Draft+, or +Expired+, it cannot be modified – only deleted. To re-list a Sold listing, a new listing must be created.
+  #
+  # @macro need_auth
+  #
+  # @macro listing_id
+  # @macro listing_params
+  # @return [Boolean]
+  def edit_listing(listing_id, data={})
+    authenticated? do
+      query_and_build "marketplace/listings/#{listing_id}", {}, :post, data
+    end
+  end
+
+  # Permanently remove a listing from the Marketplace.
+  #
+  # @macro need_auth
+  #
+  # @macro listing_id
+  # @return [Boolean]
+  def delete_listing(listing_id)
+    authenticated? do
+      query_and_build "marketplace/listings/#{listing_id}", {}, :delete
+    end
+  end
+
+  # View the data associated with an order.
+  #
+  # @macro need_auth
+  #
+  # @!macro [new] order_id
+  #   @param order_id [Integer] order id
+  # @return [Hash] order information
+  def get_order(order_id)
+    authenticated? do
+      query_and_build "marketplace/orders/#{order_id}"
+    end
+  end
+
+  # Edit the data associated with an order.
+  #
+  # The conditions under which an order is permitted to transition from one status to another are best summarized by a state diagram.
+  #
+  # http://www.discogs.com/developers/_images/order_state_transitions.png
+  #
+  # Rather than implementing this logic in your application, the response contains a next_status key – an array of valid next statuses for this order, which you can display to the user in (for example) a dropdown control. This also renders your application more resilient to any future changes in the order status logic.
+  #
+  # Changing the order status using this resource will always message the buyer with:
+  #
+  #   Seller changed status from Old Status to New Status
+  #
+  # and does not provide a facility for including a custom message along with the change. For more fine-grained control, use the Add a new message resource, which allows you to simultaneously add a message and change the order status.
+  #
+  # If the order status is neither +cancelled+, +Payment Received+, nor +Shipped+, you can change the shipping. Doing so will send an invoice to the buyer and set the order status to Invoice Sent. (For that reason, you cannot set the shipping and the order status in the same request.)
+  #
+  # @macro need_auth
+  #
+  # @macro order_id
+  # @param [Hash] data order parameters
+  # @option data [String (Optional)] :status The new status of the order. Must *EXACTLY* match one of:
+  #   * +New Order+
+  #   * +Buyer Contacted+
+  #   * +Invoice Sent+
+  #   * +Payment Pending+
+  #   * +Payment Received+
+  #   * +Shipped+
+  #   * +Cancelled (Non-Paying Buyer)+
+  #   * +Cancelled (Item Unavailable)+
+  #   * +Cancelled (Per Buyer's Request)+
+  #   * the order's current status
+  #     - Furthermore, the new status must be present in the order’s next_status list. For more information about order statuses, see #edit_order[#edit_order-instance_method].
+  # @option data [Float (Optional)] :shipping The order shipping amount.
+  #
+  #   As a side-effect of setting this value, the buyer is invoiced and the order status is set to +Invoice Sent+. For more information, see #edit_order[#edit_order-instance_method].
+  # @return [Hash] order information
+  def edit_order(order_id, data={})
+    authenticated? do
+      query_and_build "marketplace/orders/#{order_id}", {}, :post, data
+    end
+  end
 
-    data = query_api("search", params)
-    resource = Discogs::Search.new(data)
+  # Returns a list of the authenticated user’s orders. Accepts Pagination parameters.
+  #
+  # @macro need_auth
+  #
+  # @param [Hash] params status, sort, sort_order, and pagination parameters
+  # @option params [String (Optional)] :status The new status of the order. Must *EXACTLY* match one of:
+  #   * +All+
+  #   * +New Order+
+  #   * +Buyer Contacted+
+  #   * +Invoice Sent+
+  #   * +Payment Pending+
+  #   * +Payment Received+
+  #   * +Shipped+
+  #   * +Merged+
+  #   * +Order Changed+
+  #   * +Cancelled+
+  #   * +Cancelled (Non-Paying Buyer)+
+  #   * +Cancelled (Item Unavailable)+
+  #   * +Cancelled (Per Buyer's Request)+
+  # @option params [String (Optional)] :sort Sort items with this field. Must *EXACTLY* match one of:
+  #   * +id+
+  #   * +buyer+
+  #   * +created+
+  #   * +status+
+  #   * +last_activity+
+  # @option params [String (Optional)] :sort_order Sort items in a particular order. Must *EXACTLY* match one of:
+  #   * +asc+
+  #   * +desc+
+  # @option params [Hash (Optional)] :pagination Pagination parameters
+  # @return [Hash] list of orders meeting specified criteria
+  def list_orders(params={})
+    authenticated? do
+      query_and_build "marketplace/orders", params
+    end
+  end
+
+  # Returns a list of the order’s messages with the most recent first. Accepts Pagination parameters.
+  #
+  # @macro need_auth
+  #
+  # @macro order_id
+  # @macro uses_pagination
+  # @return [Hash] messages for order
+  def list_order_messages(order_id, pagination={})
+   authenticated? do
+     query_and_build "marketplace/orders#{order_id}/messages", pagination
+   end
+  end
+
+  alias_method :get_order_messages, :list_order_messages
+
+  # Adds a new message to the order’s message log.
+  #
+  # When posting a new message, you can simultaneously change the order status. If you do, the message will automatically be prepended with:
+  #   Seller changed status from Old Status to New Status\n\n
+  # While message and status are each optional, one or both must be present.
+  #
+  # @macro need_auth
+  #
+  # @macro order_id
+  # @param [Hash] data new message metadata
+  # @option data [String (Optional)] :message The body of the message to send to the buyer.
+  # @option data [String (Optional)] :status The new status of the corresponding order.
+  #   * For more information about order statuses, see #edit_order[#edit_order-instance_method]
+  # @return [Hash] created message metadata
+  def create_order_message(order_id, data={})
+    authenticated? do
+      query_and_build "marketplace/orders/#{order_id}/messages", {}, :post, data
+    end
+  end
+
+  # Retrieve price suggestions for the provided Release ID. If no suggestions are available, an empty object will be returned.
+  #
+  # Authentication is required, and the user needs to have filled out their seller settings. Suggested prices will be denominated in the user’s selling currency.
+  #
+  # @macro need_auth
+  #
+  # @macro release_id
+  # @return [Hash] price suggestions information
+  def get_price_suggestions(release_id)
+    authenticated? do
+      query_and_build "marketplace/price_suggestions/#{release_id}"
+    end
+  end
+
+  # Calculate the fee for the provided price and currency.
+  #
+  # @param [Float] price price of item
+  # @param [String (Optional)] currency currency to return the fee in. Must *EXACTLY* match one of:
+  #   * +USD+
+  #   * +GBP+
+  #   * +EUR+
+  #   * +CAD+
+  #   * +AUD+
+  #   * +JPY+
+  def get_fee(price, currency="USD")
+    query_and_build "marketplace/fee/#{price}/#{currency}"
+  end
+
+  # Retrieve an image by filename.
+  #
+  # It’s unlikely that you’ll ever have to construct an image URL; images keys on other resources use fully-qualified URLs, including hostname and protocol.
+  #
+  # @macro need_auth
+  #
+  # @param [String (Required)] filename the name of the image file
+  # @return [Binary] binary image file
+  def get_image(filename)
+    authenticated? do
+      @access_token.get("/image/#{filename}").body
+    end
+  end
+
+  def search(term, params={})
+    parameters = {:q => term}.merge(params)
+
+    query_and_build "database/search", parameters
+  end
 
-    resource.build_with_resp!
+  def raw(url)
+    uri    = URI.parse(url)
+    params = CGI.parse(uri.query.to_s)
+
+    query_and_build uri.path, params
   end
 
  private
 
-  def query_and_build(path, klass, params={})
-    data = query_api(path, params)
-    resource = klass.send(:new, data)
-    resource.build!
+  def query_and_build(path, params={}, method=:get, body=nil)
+    parameters = {:f => "json"}.merge(params)
+    data = query_api(path, params, method, body)
+    hash = JSON.parse(data)
+
+    Hashie::Mash.new(hash)
   end
 
   # Queries the API and handles the response.
-  def query_api(path, params={})
-    response = make_request(path, params)
+  def query_api(path, params, method, body)
+    response = make_request(path, params, method, body)
 
     raise_unknown_resource(path) if response.code == "404"
+    raise_authentication_error(path) if response.code == "401"
     raise_internal_server_error if response.code == "500"
 
     # Unzip the response data, or just read it in directly
     # if the API responds without gzipping.
     response_body = nil
     begin
-        inflated_data = Zlib::GzipReader.new(StringIO.new(response.body))
-        response_body = inflated_data.read
+      inflated_data = Zlib::GzipReader.new(StringIO.new(response.body))
+      response_body = inflated_data.read
     rescue Zlib::GzipFile::Error
-        response_body = response.body
+      response_body = response.body
     end
 
     response_body
   end
 
   # Generates a HTTP request and returns the response.
-  def make_request(path, params={})
-    uri = build_uri(path, params)
+  def make_request(path, params, method, body)
+    uri           = build_uri(path, params)
+    formatted     = "#{uri.path}?#{uri.query}"
+    output_format = params.fetch(:f, "json")
+    headers       = {"Accept"          => "application/#{output_format}",
+                     "Accept-Encoding" => "gzip,deflate",
+                     "User-Agent"      => @app_name}
 
-    request = Net::HTTP::Get.new(uri.path + "?" + uri.query)
-    request.add_field("Accept", "application/xml")
-    request.add_field("Accept-Encoding", "gzip,deflate")
-    request.add_field("User-Agent", @app_name)
+    if authenticated?
+      if [:post, :put].include?(method)
+        headers["Content-Type"] = "application/json"
+        @access_token.send(method, formatted, JSON(body), headers)
+      else
+        @access_token.send(method, formatted, headers)
+      end
+    else
+      # All non-authenticated endpoints are GET.
+      request = Net::HTTP::Get.new(formatted)
 
-    Net::HTTP.new(uri.host).start do |http|
-      http.request(request)
+      headers.each do |h, v|
+        request.add_field(h, v)
+      end
+
+      Net::HTTP.new(uri.host).start do |http|
+        http.request(request)
+      end
     end
   end
 
   def build_uri(path, params={})
-    parameters = { :f => "xml" }.merge(params)
-    querystring = "?" + parameters.map { |key, value| "#{key}=#{value}" }.sort.join("&")
+    output_format = params.fetch(:f, "json")
+    parameters    = {:f => output_format}.merge(params)
+    querystring   = "?" + URI.encode_www_form(prepare_hash(parameters))
 
     URI.parse(File.join(@@root_host, URI.encode(sanitize_path(path, URI.escape(querystring)))))
   end
 
+  # Stringifies keys and sorts.
+  def prepare_hash(h)
+    result = {}
+
+    h.each do |k, v|
+      result[k.to_s] = v
+    end
+
+    result.sort
+  end
+
   def sanitize_path(*path_parts)
     clean_path = path_parts.map { |part| part.gsub(/\s/, '+') }
-
     clean_path.join
   end
 
-  def raise_unknown_resource(path='')
+  def raise_unknown_resource(path="")
     raise Discogs::UnknownResource, "Unknown Discogs resource: #{path}"
   end
 
   def raise_internal_server_error
-    raise Discogs::InternalServerError, "The remote server cannot complete the request"
+    raise Discogs::InternalServerError, "The API server cannot complete the request"
+  end
+
+  def raise_authentication_error(path="")
+    raise Discogs::AuthenticationError, "Authentication is required for this resource: #{path}"
   end
 
 end