disconnect: A JavaScript repository from CoreyT355

About

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

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

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

CoreyT355/disconnect