/disconnect

An easy to use Node.js client with OAuth support to connect with the discogs.com API v2.0

Primary LanguageJavaScriptMIT LicenseMIT

About

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

Dependency Status

This is a fork updated to allow CommonJS compaibility, and use ES6 as the main codebase.

As such this can now be imported using:

import { Client } from 'disconnect';

Still need types for TS support.

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

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

Go!

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

let db = new Discogs().database();
db.getRelease(176126, (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.

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

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

Promises

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

let db = new Discogs().database();
db.getRelease(1)
    .then((release) => { 
        return db.getArtist(release.artists[0].id);
    })
    .then((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
let dis = new Discogs().setConfig({outputFormat: 'html'});

Discogs Auth

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

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

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

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

let 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', (req, res) => {
    let oAuth = new Discogs().oauth();
    oAuth.getRequestToken(
        'YOUR_CONSUMER_KEY', 
        'YOUR_CONSUMER_SECRET', 
        'http://your-script-url/callback', 
        (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', (req, res) => {
    let oAuth = new Discogs(requestData).oauth();
    oAuth.getAccessToken(
        req.query.oauth_verifier, // Verification code sent back by Discogs
        (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', (req, res) => {
    let dis = new Discogs(accessData);
    dis.getIdentity((err, data) => {
        res.send(data);
    });
});

Images

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

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

Resources

License

MIT