parrfolio / discojs

Easiest way to use the Discogs API in Javascript :musical_note:

Discojs

Easiest way to use the Discogs API in Javascript 🎵

Installation

npm install --save discojs

Usage example

import Discojs from 'discojs'

const client = new Discojs({
  userToken: process.env.USER_TOKEN,
})

// Methods return promises

client
  .searchArtist('Jacob Desvarieux')
  .then((data) => {
    doSomethingWith(data)
  })
  .catch((error) => {
    console.warn('Oops, something went wrong!', error)
  })

// If you're using ES7, you can use async functions

async function notifyShipmentForOrder(orderId) {
  const result = await client.sendMessageForOrder(orderId, {
    message: 'Your order is dispatched!',
    status: 'Shipped',
  })
  return result.timestamp
}

// Just chain methods!

client
  .getIdentity()
  .then((identity) => {
    const { username } = identity
    return client.addToWantlist({
      username,
      releaseId: 1189932,
      notes: 'Must buy this!',
      rating: 4,
    })
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.warn(error)
  })

API Reference

Discojs instance

const options = {
  userAgent,
  outputFormat,
  userToken,
  consumerKey,
  consumerSecret,
  requestLimit,
  requestLimitAuth,
  requestLimitInterval,
  fetchOptions,
}

const client = new Discojs(options)

Key	Type	Default	Details
userAgent	string	Discojs/1.1.0
outputFormat	string	discogs	Must be discogs, plaintext or html
userToken	string	-	For auth purposes
consumerKey	string	-	For auth purposes
consumerSecret	string	-	For auth purposes
requestLimit	int	25	For API throttling purposes when not authenticated
requestLimitAuth	int	60	For API throttling purposes when authenticated
requestLimitInterval	int	60000
fetchOptions	object	{}	Options to be passed to fetch

Methods

Documentation about methods is available in the wiki.

• Static methods
  • getSupportedCurrencies
  • getReleaseConditions
  • getSleeveConditions

• Database
  • Search
    • searchDatabase
  • Releases
    • getRelease
    • searchRelease
  • Masters
    • getMaster
    • getVersionsForMaster
  • Artists
  • getArtist
  • getReleasesForArtist
  • searchArtist
  • Labels
    • getLabel
    • getReleasesForLabel
    • searchLabel

• Lists
  • getItemsInList

• Marketplace
  • Listings
    • getListing
    • editListing
    • removeListing
    • createListing
  • Orders
    • listOrders
    • getOrder
    • editOrder
    • listMessagesForOrder
    • sendMessageForOrder
  • Fees
    • getFee
  • Price suggestions
    • getPriceSuggestions

• User
  • Inventory
    • getInventory
  • Identity
    • getIdentity
    • Profile
      • getProfile
      • editProfile
    • Submissions
      • getSubmissionsForUser
    • Contributions
      • getContributionsForUser
  • Collection
    • Folders
      • listFoldersForUser
      • getFolderForUser
      • editFolderForUser
      • removeFolderForUser
      • createFolderForUser
      • getItemsInFolderForUser
    • Custom fields
      • getCustomFields
    • Collection value
      • getValue
  • Wantlist
    • getWantlist
    • addToWantlist
    • removeFromWantlist
  • Lists
    • getListsForUser

Tests

As several methods need authentication, you'll need 2 environment variables: DGS_USERNAME and USER_TOKEN.

Create a .env file at the root of the directory, and add the following lines:

DGS_USERNAME=0ctocat
USER_TOKEN=7h1515myu53r70k3n

⚠️ Use a test account as public information will be edited.

As stated by Discogs API, some methods need a seller account. As I do not have one, I could not test them (which explains the coverage).

npm run test

When running tests, go grab a cup of coffee as this may be long because of Discogs API rate limiting.

Credits

Inspired by disconnect from @bartve