Class: Discogs::Wrapper

Inherits:
Object
  • Object
show all
Includes:
Authentication
Defined in:
lib/discogs/wrapper.rb

Constant Summary collapse

@@root_host = 
"https://api.discogs.com"

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Authentication

#any_authentication?, #auth_params, #authenticate, #authenticated?, #get_request_token, #self_authenticating?, #user_facing?

Constructor Details

#initialize(app_name, auth_opts = {}) ⇒ Wrapper

Returns a new instance of Wrapper.



21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/discogs/wrapper.rb', line 21

def initialize(app_name, auth_opts={})
  @app_name     = app_name

  # Allow for backwards-compatibility with v2.0.0
  if auth_opts.is_a?(Hash)
    @access_token = auth_opts[:access_token]
    @user_token   = auth_opts[:user_token]
  else
    @access_token = auth_opts
  end
end

Instance Attribute Details

#access_token ⇒ Object

Returns the value of attribute access_token.



19
20
21
 
# File 'lib/discogs/wrapper.rb', line 19

def access_token
  @access_token
end

#app_name ⇒ Object (readonly)

Returns the value of attribute app_name.



18
19
20
 
# File 'lib/discogs/wrapper.rb', line 18

def app_name
  @app_name
end

#user_token ⇒ Object

Returns the value of attribute user_token.



19
20
21
 
# File 'lib/discogs/wrapper.rb', line 19

def user_token
  @user_token
end

Instance Method Details

#add_release_to_user_folder(username, folder_id, release_id) ⇒ Hash Also known as: add_instance_to_user_folder

Note:

Authentication as the owner is required.

Add a release to a folder in a user’s collection.

The folder_id must be non-zero – you can use 1 for “Uncategorized”.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • release_id (Integer) —

    release id

Returns:

  • (Hash) —

    new instance metadata



252
253
254
255
256
 
# File 'lib/discogs/wrapper.rb', line 252

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

#add_release_to_user_wantlist(username, release_id, data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Add a release to a user’s wantlist.

Parameters:

  • username (String) —

    username

  • release_id (Integer) —

    release id

  • data (Hash) (defaults to: {}) —

    optional parameters:

Options Hash (data):

  • :notes (String) —

    User notes to associate with this release.

  • :rating (Integer) —

    User’s rating of this release, from 0 (unrated) to 5 (best). Defaults to 0.

Returns:

  • (Hash) —

    new wantlist entry



174
175
176
177
178
 
# File 'lib/discogs/wrapper.rb', line 174

def add_release_to_user_wantlist(username, release_id, data={})
  authenticated? do
    query_and_build "users/#{username}/wants/#{release_id}", {}, :put, data
  end
end

#create_listing(data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Create a Marketplace listing.

Parameters:

  • data (Hash) (defaults to: {}) —

    parameters for listing

Options Hash (data):

  • :release_id (Integer (Required)) —

    The ID of the release that this listing represents.

  • :condition (String (Optional)) —

    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)

  • :sleeve_condition (String (Optional)) — default: +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

  • :price (Float (Required)) —

    The price of the item (in the seller’s currency).

  • :comments (String (Optional)) —

    Any remarks about the item that will be displayed to buyers.

  • :allow_offers (Boolean (Optional)) — default: false —

    Whether or not to allow buyers to make offers on the item. Defaults to false.

  • :status (String (Optional)) — default: +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

  • :external_id (String (Optional)) —

    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.

  • :weight (Float (Optional)) —

    The weight, in grams, of this listing, for the purpose of calculating shipping.

  • :format_quantity (Integer (Optional)) —

    The number of items this listing counts as, for the purpose of calculating shipping. This field is called “Counts As” on the Discogs website.

Returns:

  • (Hash) —

    listing metadata



498
499
500
501
502
 
# File 'lib/discogs/wrapper.rb', line 498

def create_listing(data={})
  authenticated? do
    query_and_build "marketplace/listings", {}, :post, data
  end
end

#create_order_message(order_id, data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

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.

Parameters:

  • order_id (Integer) —

    order id

  • data (Hash) (defaults to: {}) —

    new message metadata

Options Hash (data):

  • :message (String (Optional)) —

    The body of the message to send to the buyer.

  • :status (String (Optional)) —

    The new status of the corresponding order.

    • For more information about order statuses, see #edit_order

Returns:

  • (Hash) —

    created message metadata



651
652
653
654
655
 
# File 'lib/discogs/wrapper.rb', line 651

def create_order_message(order_id, data={})
  authenticated? do
    query_and_build "marketplace/orders/#{order_id}/messages", {}, :post, data
  end
end

#create_user_folder(username, data = {}) ⇒ Hash Also known as: add_user_folder

Note:

Authentication as the owner is required.

Create a new folder in a user’s collection.

Parameters:

  • username (String) —

    username

  • data (Hash) (defaults to: {}) —

    folder parameters

Options Hash (data):

  • :name (String) —

    The name of the newly-created folder (Required).

Returns:

  • (Hash) —

    new folder metadata



385
386
387
388
389
 
# File 'lib/discogs/wrapper.rb', line 385

def create_user_folder(username, data={})
  authenticated? do
    query_and_build "users/#{username}/collection/folders", {}, :post, data
  end
end

#delete_instance_in_user_folder(username, folder_id, release_id, instance_id) ⇒ Boolean Also known as: delete_release_in_user_folder

Note:

Authentication as the owner is required.

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.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • release_id (Integer) —

    release id

  • instance_id (Integer) —

    instance id

Returns:

  • (Boolean) 


292
293
294
295
296
 
# File 'lib/discogs/wrapper.rb', line 292

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

#delete_listing(listing_id) ⇒ Boolean

Note:

Authentication as the owner is required.

Permanently remove a listing from the Marketplace.

Parameters:

  • listing_id (Integer) —

    listing id

Returns:

  • (Boolean) 


525
526
527
528
529
 
# File 'lib/discogs/wrapper.rb', line 525

def delete_listing(listing_id)
  authenticated? do
    query_and_build "marketplace/listings/#{listing_id}", {}, :delete
  end
end

#delete_release_in_user_wantlist(username, release_id) ⇒ Boolean Also known as: delete_release_from_user_wantlist

Note:

Authentication as the owner is required.

Remove a release from a user’s wantlist.

Parameters:

  • username (String) —

    username

  • release_id (Integer) —

    release id

Returns:

  • (Boolean) 


203
204
205
206
207
 
# File 'lib/discogs/wrapper.rb', line 203

def delete_release_in_user_wantlist(username, release_id)
  authenticated? do
    query_and_build "users/#{username}/wants/#{release_id}", {}, :delete
  end
end

#delete_user_folder(username, folder_id) ⇒ Boolean

Note:

Authentication as the owner is required.

Delete a folder from a user’s collection. A folder must be empty before it can be deleted.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

Returns:

  • (Boolean) 


415
416
417
418
419
 
# File 'lib/discogs/wrapper.rb', line 415

def delete_user_folder(username, folder_id)
  authenticated? do
    query_and_build "users/#{username}/collection/folders#{folder_id}", {}, :delete
  end
end

#edit_field_on_instance_in_user_folder(username, folder_id, release_id, instance_id, field_id, data = {}) ⇒ Object

Note:

Authentication as the owner is required.

Change the value of a notes field on a particular instance.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • release_id (Integer) —

    release id

  • instance_id (Integer) —

    instance id

  • field_id (Integer) —

    field id

  • data (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (data):

  • :value (String) —

    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.



311
312
313
314
315
 
# File 'lib/discogs/wrapper.rb', line 311

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

#edit_listing(listing_id, data = {}) ⇒ Hash, Boolean

Note:

Authentication as the owner is required.

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.

Parameters:

  • listing_id (Integer) —

    listing id

  • data (Hash) (defaults to: {}) —

    parameters for listing

Options Hash (data):

  • :release_id (Integer (Required)) —

    The ID of the release that this listing represents.

  • :condition (String (Optional)) —

    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)

  • :sleeve_condition (String (Optional)) — default: +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

  • :price (Float (Required)) —

    The price of the item (in the seller’s currency).

  • :comments (String (Optional)) —

    Any remarks about the item that will be displayed to buyers.

  • :allow_offers (Boolean (Optional)) — default: false —

    Whether or not to allow buyers to make offers on the item. Defaults to false.

  • :status (String (Optional)) — default: +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

  • :external_id (String (Optional)) —

    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.

  • :weight (Float (Optional)) —

    The weight, in grams, of this listing, for the purpose of calculating shipping.

  • :format_quantity (Integer (Optional)) —

    The number of items this listing counts as, for the purpose of calculating shipping. This field is called “Counts As” on the Discogs website.

Returns:

  • (Hash) —

    listing metadata

  • (Boolean) 


513
514
515
516
517
 
# File 'lib/discogs/wrapper.rb', line 513

def edit_listing(listing_id, data={})
  authenticated? do
    query_and_build "marketplace/listings/#{listing_id}", {}, :post, data
  end
end

#edit_order(order_id, data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

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.

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.)

Parameters:

  • order_id (Integer) —

    order id

  • data (Hash) (defaults to: {}) —

    order parameters

Options Hash (data):

  • :status (String (Optional)) —

    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.

  • :shipping (Float (Optional)) —

    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.

Returns:

  • (Hash) —

    order information



580
581
582
583
584
 
# File 'lib/discogs/wrapper.rb', line 580

def edit_order(order_id, data={})
  authenticated? do
    query_and_build "marketplace/orders/#{order_id}", {}, :post, data
  end
end

#edit_release_in_user_folder(username, folder_id, release_id, instance_id = 1, data = {}) ⇒ Boolean Also known as: edit_instance_in_user_folder

Note:

Authentication as the owner is required.

Change the rating on a release and/or move the instance to another folder.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • release_id (Integer) —

    release id

  • instance_id (Integer) (defaults to: 1) —

    instance id

  • data (Hash) (defaults to: {}) —

    optional parameters

Options Hash (data):

  • :rating (Integer) —

    User’s rating of this release, from 0 (unrated) to 5 (best).

  • :folder_id (Integer) —

    The ID of the folder to move the release into.

Returns:

  • (Boolean) 


273
274
275
276
277
 
# File 'lib/discogs/wrapper.rb', line 273

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

#edit_release_in_user_wantlist(username, release_id, data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Edit the notes (or rating) on a release in a user’s wantlist.

Parameters:

  • username (String) —

    username

  • release_id (Integer) —

    release id

  • data (Hash) (defaults to: {}) —

    optional parameters:

Options Hash (data):

  • :notes (String) —

    User notes to associate with this release.

  • :rating (Integer) —

    User’s rating of this release, from 0 (unrated) to 5 (best). Defaults to 0.

Returns:

  • (Hash) —

    updated wantlist entry



190
191
192
193
194
 
# File 'lib/discogs/wrapper.rb', line 190

def edit_release_in_user_wantlist(username, release_id, data={})
  authenticated? do
    query_and_build "users/#{username}/wants/#{release_id}", {}, :post, data
  end
end

#edit_user(username, data = {}) ⇒ Object

Note:

Authentication as the owner is required.

Edit a user’s profile data.

Parameters:

  • username (String) —

    username

  • data (Hash) (defaults to: {}) —

    data to update, with the optional keys:

Options Hash (data):

  • :name (String) —

    The real name of the user.

  • :home_page (String) —

    The user’s website.

  • :location (String) —

    The geographical location of the user.

  • :profile (String) —

    Biographical information about the user.



235
236
237
238
239
 
# File 'lib/discogs/wrapper.rb', line 235

def edit_user(username, data={})
  authenticated? do
    query_and_build "users/#{username}", {}, :post, data
  end
end

#edit_user_folder(username, folder_id, data = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Edit a folder’s metadata. Folders 0 and 1 cannot be renamed.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • data (Hash) (defaults to: {}) —

    folder parameters

Options Hash (data):

  • :name (String) —

    The name of the folder (Required).

Returns:

  • (Hash) —

    updated folder metadata



402
403
404
405
406
 
# File 'lib/discogs/wrapper.rb', line 402

def edit_user_folder(username, folder_id, data={})
  authenticated? do
    query_and_build "users/#{username}/collection/folders#{folder_id}", {}, :post, data
  end
end

#get_artist(artist_id) ⇒ Hash

Retrieves an artist by ID.

Parameters:

  • artist_id (Integer) —

    artist id

Returns:

  • (Hash) —

    the artist with provided artist_id



64
65
66
 
# File 'lib/discogs/wrapper.rb', line 64

def get_artist(artist_id)
  query_and_build "artists/#{artist_id}"
end

#get_artists_releases(artist_id, pagination = {}) ⇒ Hash Also known as: get_artist_releases

Returns a list of Releases and Masters associated with the artist. Accepts Pagination parameters.

Parameters:

  • artist_id (Integer) —

    artist id

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    the releases for artist with provided artist_id



72
73
74
 
# File 'lib/discogs/wrapper.rb', line 72

def get_artists_releases(artist_id, pagination={})
  query_and_build "artists/#{artist_id}/releases", pagination
end

#get_fee(price, currency = "USD") ⇒ Object

Calculate the fee for the provided price and currency.

Parameters:

  • price (Float) —

    price of item

  • currency (String (Optional)) (defaults to: "USD") —

    currency to return the fee in. Must EXACTLY match one of:

    • USD

    • GBP

    • EUR

    • CAD

    • AUD

    • JPY



681
682
683
 
# File 'lib/discogs/wrapper.rb', line 681

def get_fee(price, currency="USD")
  query_and_build "marketplace/fee/#{CGI.escape(price)}/#{currency}"
end

#get_identity ⇒ Hash

Note:

Authentication as the owner is required.

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.

Returns:

  • (Hash) —

    authenticated user information



219
220
221
222
223
 
# File 'lib/discogs/wrapper.rb', line 219

def get_identity
  authenticated? do
    query_and_build "oauth/identity"
  end
end

#get_image(filename) ⇒ Binary

Note:

Authentication as the owner is required.

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.

Parameters:

  • filename (String (Required)) —

    the name of the image file

Returns:

  • (Binary) —

    binary image file



693
694
695
696
697
698
699
700
701
 
# File 'lib/discogs/wrapper.rb', line 693

def get_image(filename)
  authenticated? do
    if user_facing?
      @access_token.get("/images/#{filename}").body
    else
      query_api("images/#{filename}")
    end
  end
end

#get_label(label_id) ⇒ Hash

Retrieves a label by ID.

Parameters:

  • label_id (Integer) —

    label id

Returns:

  • (Hash) —

    the label with provided id



82
83
84
 
# File 'lib/discogs/wrapper.rb', line 82

def get_label(label_id)
  query_and_build "labels/#{label_id}"
end

#get_labels_releases(label_id, pagination = {}) ⇒ Hash Also known as: get_label_releases

Returns a list of Releases associated with the label. Accepts Pagination parameters.

Parameters:

  • label_id (Integer) —

    label id

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    the releases for label with provided id



90
91
92
 
# File 'lib/discogs/wrapper.rb', line 90

def get_labels_releases(label_id, pagination={})
  query_and_build "labels/#{label_id}/releases", pagination
end

#get_listing(listing_id) ⇒ Hash

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.

Parameters:

  • listing_id (Integer) —

    listing id

Returns:

  • (Hash) —

    listing with listing_id



456
457
458
 
# File 'lib/discogs/wrapper.rb', line 456

def get_listing(listing_id)
  query_and_build "marketplace/listings/#{listing_id}"
end

#get_master_release(master_release_id) ⇒ Hash Also known as: get_master

Retrieves a master release by ID.

Parameters:

  • master_release_id (Integer) —

    master release id

Returns:

  • (Hash) —

    the master release with provided master_release_id



45
46
47
 
# File 'lib/discogs/wrapper.rb', line 45

def get_master_release(master_release_id)
  query_and_build "masters/#{master_release_id}"
end

#get_master_release_versions(master_release_id, pagination = {}) ⇒ Hash

Retrieves a list of all Releases that are versions of this master. Accepts Pagination parameters.

Parameters:

  • master_release_id (Integer) —

    master release id

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    the master release with the provided master_release_id, along with versions



56
57
58
 
# File 'lib/discogs/wrapper.rb', line 56

def get_master_release_versions(master_release_id, pagination={})
  query_and_build "masters/#{master_release_id}/versions", pagination
end

#get_order(order_id) ⇒ Hash

Note:

Authentication as the owner is required.

View the data associated with an order.

Parameters:

  • order_id (Integer) —

    order id

Returns:

  • (Hash) —

    order information



538
539
540
541
542
 
# File 'lib/discogs/wrapper.rb', line 538

def get_order(order_id)
  authenticated? do
    query_and_build "marketplace/orders/#{order_id}"
  end
end

#get_price_suggestions(release_id) ⇒ Hash

Note:

Authentication as the owner is required.

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.

Parameters:

  • release_id (Integer) —

    release id

Returns:

  • (Hash) —

    price suggestions information



665
666
667
668
669
 
# File 'lib/discogs/wrapper.rb', line 665

def get_price_suggestions(release_id)
  authenticated? do
    query_and_build "marketplace/price_suggestions/#{release_id}"
  end
end

#get_release(release_id) ⇒ Hash

Retrieves a release by ID.

Parameters:

  • release_id (Integer) —

    release id

Returns:

  • (Hash) —

    the release with provided release_id



37
38
39
 
# File 'lib/discogs/wrapper.rb', line 37

def get_release(release_id)
  query_and_build "releases/#{release_id}"
end

#get_user(username) ⇒ Hash

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.

Parameters:

  • username (String) —

    username

Returns:

  • (Hash) —

    the user with provided username



106
107
108
 
# File 'lib/discogs/wrapper.rb', line 106

def get_user(username)
  query_and_build "users/#{username}"
end

#get_user_collection(username, pagination = {}) ⇒ Hash

Get a collection for a user by username

Shortcut method for #get_user_folder_releases

Parameters:

  • username (String) —

    username

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    the user with provided username



117
118
119
 
# File 'lib/discogs/wrapper.rb', line 117

def get_user_collection(username, pagination={})
  get_user_folder_releases(username, 0, pagination)
end

#get_user_collection_fields(username) ⇒ Hash

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.

Parameters:

  • username (String) —

    username

Returns:

  • (Hash) —

    list of collection fields for the provided username



129
130
131
 
# File 'lib/discogs/wrapper.rb', line 129

def get_user_collection_fields(username)
  query_and_build "users/#{username}/collection/fields"
end

#get_user_folder(username, folder_id) ⇒ Hash

Note:

Authentication as the owner is required.

Retrieve metadata about a folder in a user’s collection.

If folder_id is not 0, authentication as the collection owner is required.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

Returns:

  • (Hash) —

    folder with folder_id



357
358
359
360
361
362
363
 
# File 'lib/discogs/wrapper.rb', line 357

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

#get_user_folder_releases(username, folder_id, params = {}) ⇒ Object

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.

Parameters:

  • username (String) —

    username

  • folder_id (Integer) —

    folder id

  • params (Hash) (defaults to: {}) —

    optional parameters

Options Hash (params):

  • :sort (String) —

    Sort items by this field. One of:

    • label

    • artist

    • title

    • catno

    • format

    • rating

    • added

    • year

  • :sort_order (String) —

    Sort items in a particular order. One of:

    • asc

    • desc



340
341
342
343
344
345
346
 
# File 'lib/discogs/wrapper.rb', line 340

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

#get_user_folders(username) ⇒ Hash

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.

Parameters:

  • username (String) —

    username

Returns:

  • (Hash) —

    folder listing



373
374
375
 
# File 'lib/discogs/wrapper.rb', line 373

def get_user_folders(username)
  query_and_build "users/#{username}/collection/folders"
end

#get_user_inventory(username, params = {}) ⇒ Hash

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.

Parameters:

  • username (String) —

    username

  • params (Hash) (defaults to: {}) —

    sort/order/pagination parameters

Options Hash (params):

  • :status (String) —

    Only show items with this status

  • :sort (String) —

    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)

  • :sort_order (String) —

    Sort items in a particular order. One of:

    • asc

    • desc

Returns:

  • (Hash) —

    listing in user’s inventory



445
446
447
 
# File 'lib/discogs/wrapper.rb', line 445

def get_user_inventory(username, params={})
  query_and_build "users/#{username}/inventory", params
end

#get_user_want(username, release_id) ⇒ Hash

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.

Parameters:

  • username (String) —

    username

  • release_id (Integer) —

    release id

Returns:

  • (Hash) —

    wantlist for the provided username



159
160
161
 
# File 'lib/discogs/wrapper.rb', line 159

def get_user_want(username, release_id)
  query_and_build "users/#{username}/wants/#{release_id}"
end

#get_user_wantlist(username, pagination = {}) ⇒ Hash Also known as: get_user_wants

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.

Parameters:

  • username (String) —

    username

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    wantlist for the provided username



144
145
146
 
# File 'lib/discogs/wrapper.rb', line 144

def get_user_wantlist(username, pagination={})
  query_and_build "users/#{username}/wants", pagination
end

#list_order_messages(order_id, pagination = {}) ⇒ Hash Also known as: get_order_messages

Note:

Authentication as the owner is required.

Returns a list of the order’s messages with the most recent first. Accepts Pagination parameters.

Parameters:

  • order_id (Integer) —

    order id

  • pagination (Hash) (defaults to: {}) —

    pagination parameters

Returns:

  • (Hash) —

    messages for order



629
630
631
632
633
 
# File 'lib/discogs/wrapper.rb', line 629

def list_order_messages(order_id, pagination={})
 authenticated? do
   query_and_build "marketplace/orders/#{order_id}/messages", pagination
 end
end

#list_orders(params = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Returns a list of the authenticated user’s orders. Accepts Pagination parameters.

Parameters:

  • params (Hash) (defaults to: {}) —

    status, sort, sort_order, and pagination parameters

Options Hash (params):

  • :status (String (Optional)) —

    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)

  • :sort (String (Optional)) —

    Sort items with this field. Must EXACTLY match one of:

    • id

    • buyer

    • created

    • status

    • last_activity

  • :sort_order (String (Optional)) —

    Sort items in a particular order. Must EXACTLY match one of:

    • asc

    • desc

  • :pagination (Hash (Optional)) —

    Pagination parameters

Returns:

  • (Hash) —

    list of orders meeting specified criteria



616
617
618
619
620
 
# File 'lib/discogs/wrapper.rb', line 616

def list_orders(params={})
  authenticated? do
    query_and_build "marketplace/orders", params
  end
end

#raw(url, additional_params = {}) ⇒ Hash

Fetch response from API using a fully-qualified URL.

Parameters:

  • API (String (Required)) —

    endpoint

Returns:

  • (Hash) —

    API response



720
721
722
723
724
725
 
# File 'lib/discogs/wrapper.rb', line 720

def raw(url, additional_params={})
  uri    = URI.parse(url)
  params = CGI.parse(uri.query.to_s).merge(additional_params)

  query_and_build uri.path, params
end

#search(term, params = {}) ⇒ Hash

Note:

Authentication as the owner is required.

Perform a search.

Parameters:

  • term (String (Required)) —

    to search.

Returns:

  • (Hash) —

    search results



709
710
711
712
713
714
 
# File 'lib/discogs/wrapper.rb', line 709

def search(term, params={})
  authenticated? do
    parameters = {:q => term}.merge(params)
    query_and_build "database/search", parameters
  end
end