Class: Discogs::Wrapper

Inherits:
Object
  • Object
show all
Includes:
Authentication
Defined in:
lib/wrapper/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.



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

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.



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

def access_token
  @access_token
end

#app_name ⇒ Object (readonly)

Returns the value of attribute app_name.



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

def app_name
  @app_name
end

#user_token ⇒ Object

Returns the value of attribute user_token.



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

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



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

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



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

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



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

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



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

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



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

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) 


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

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) 


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

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) 


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

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) 


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

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.



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

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) 


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

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



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

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) 


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

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



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

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.



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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