An easy to use Node.js client with OAuth support to connect with the discogs.com API v2.0
JavaScript
Latest commit e64ffd2 Nov 10, 2016 @bartve 1.0.2
Permalink
Failed to load latest commit information.
lib 1.0.2 Nov 10, 2016
test 1.0.0 Oct 27, 2016
.gitignore 0.2.0 Jun 19, 2014
HISTORY.md 1.0.2 Nov 10, 2016
LICENSE 0.7.1 Jan 26, 2016
README.md 1.0.0 Oct 27, 2016
index.js Strict mode + preparing for required authentication for database().se… Aug 11, 2014
package.json 1.0.2 Nov 10, 2016

README.md

About

disconnect is a Node.js client library that connects with the Discogs.com API v2.0.

Dependency Status

Features

  • Covers all API endpoints
  • Supports pagination, rate limiting, etc.
  • All database, marketplace and user functions implement a standard function(err, data, rateLimit) format for the callback or return a native JS Promise when no callback is provided
  • Easy access to protected endpoints with Discogs Auth
  • Includes OAuth 1.0a tools. Just plug in your consumer key and secret and do the OAuth dance
  • API functions grouped in their own namespace for easy access and isolation

Todo

  • Add more tests

Installation

NPM

Structure

The global structure of disconnect looks as follows:

require('disconnect') -> new Client() -> oauth()
                                      -> database()
                                      -> marketplace()
                                      -> user() -> collection()
                                                -> wantlist()
                                                -> list()
                      -> util

Usage

Quick start

Here are some basic usage examples that connect with the public API. Error handling has been left out for demonstrational purposes.

Init

var Discogs = require('disconnect').Client;

Go!

Get the release data for a release with the id 176126.

var db = new Discogs().database();
db.getRelease(176126, function(err, data){
    console.log(data);
});

Set your own custom User-Agent. This is optional as when omitted disconnect will set a default one with the value DisConnectClient/x.x.x where x.x.x is the installed version of disconnect.

var dis = new Discogs('MyUserAgent/1.0');

Get page 2 of USER_NAME's public collection showing 75 releases. The second param is the collection folder ID where 0 is always the "All" folder.

var col = new Discogs().user().collection();
col.getReleases('USER_NAME', 0, {page: 2, per_page: 75}, function(err, data){
    console.log(data);
});

Promises

When no callback is provided, the API functions return a native JS Promise for easy chaining.

var db = new Discogs().database();
db.getRelease(1)
    .then(function(release){ 
        return db.getArtist(release.artists[0].id);
    })
    .then(function(artist){
        console.log(artist.name);
    });

Output format

User, artist and label profiles can be formatted in different ways: plaintext, html and discogs. disconnect defaults to discogs, but the output format can be set for each client instance.

// Set the output format to HTML
var dis = new Discogs().setConfig({outputFormat: 'html'});

Discogs Auth

Just provide the client constructor with your preferred way of authentication.

// Authenticate by user token
var dis = new Discogs({userToken: 'YOUR_USER_TOKEN'});

// Authenticate by consumer key and secret
var dis = new Discogs({
    consumerKey: 'YOUR_CONSUMER_KEY', 
    consumerSecret: 'YOUR_CONSUMER_SECRET'
});

The User-Agent can still be passed for authenticated calls.

var dis = new Discogs('MyUserAgent/1.0', {userToken: 'YOUR_USER_TOKEN'});

OAuth

Below are the steps that involve getting a valid OAuth access token from Discogs. Note that in the following examples the app variable is an Express instance to handle incoming HTTP requests.

1. Get a request token

app.get('/authorize', function(req, res){
    var oAuth = new Discogs().oauth();
    oAuth.getRequestToken(
        'YOUR_CONSUMER_KEY', 
        'YOUR_CONSUMER_SECRET', 
        'http://your-script-url/callback', 
        function(err, requestData){
            // Persist "requestData" here so that the callback handler can 
            // access it later after returning from the authorize url
            res.redirect(requestData.authorizeUrl);
        }
    );
});

2. Authorize

After redirection to the Discogs authorize URL in step 1, authorize the application.

3. Get an access token

app.get('/callback', function(req, res){
    var oAuth = new Discogs(requestData).oauth();
    oAuth.getAccessToken(
        req.query.oauth_verifier, // Verification code sent back by Discogs
        function(err, accessData){
            // Persist "accessData" here for following OAuth calls 
            res.send('Received access token!');
        }
    );
});

4. Make OAuth calls

Simply provide the constructor with the accessData object persisted in step 3.

app.get('/identity', function(req, res){
    var dis = new Discogs(accessData);
    dis.getIdentity(function(err, data){
        res.send(data);
    });
});

Images

Image requests themselves don't require authentication, but obtaining the image URLs through, for example, release data does.

var db = new Discogs(accessData).database();
db.getRelease(176126, function(err, data){
    var url = data.images[0].resource_url;
    db.getImage(url, function(err, data, rateLimit){
        // Data contains the raw binary image data
        require('fs').writeFile('/tmp/image.jpg', data, 'binary', function(err){
            console.log('Image saved!');
        });
    });
});

Resources

License

MIT