Natural Pleistocene Monsters

    damn

    0.2.0 • Public • Published

    dAmn

    CircleCI npm version Coverage Status bitHound Score

    Node.js DeviantArt API client

    Quick start

    Install:

    yarn add damn
    const Damn = require('damn');
     
    const clientId = 1234
    const clientSecret = 'thisissecret'
     
    Damn.clientCredentials(clientId, clientSecret)
    .then(damn => damn.getDailyDeviations())
    .then(dailyDeviations => {
      ...
    })
     

    Client generation

    dAmn currently supports two authentication methods: Client Credentials and Implicit. Both provide access to public endpoints but only the Implicit method grants access to user-specific APIs.

    Both methods require a client_id and a client_secret to be granted an access token. These are obtained by creating an app in DeviantArt's application page.

    Public API

    The easiest way to access public API is to use the Client Credentials method, which is available via Damn.clientCredentials:

    Damn.clientCredentials('4321', 'cl13nt_s3cr3t')
    .then(damn => {
      damn.getDailyDeviations()
      ...
    })

    Where 4321 is your client_id and cl13nt_s3cr3t is your client_secret.

    The Damn.clientCredentials() call returns a promise which resolves to a Damn object, from which you can call the methods marked public described below.

    Logged-in API

    Accessing user-specific endpoints can only be done when using the Implicit authentication method. This methods requires you to provide an username, a password, a client_id and a redirect_uri for the application you created.

    If you're using this method, make sure your "OAuth2 Grant Type" settings is set to "Implicit" in your application parameters: DA application's OAuth Grant Type setting

    To instanciate a "private" client you may use the Damn.implicit method:

    const clientId = 1234
    const redirectUri = 'https://www.example.com'
    const username = 'toto'
    const password = 'h4xXx0r'
    const scope = 'basic'
     
    Damn.implicit(clientId, redirectUri, username, password, scope)
    .then(damn => {
      damn.getDailyDeviations()
      ...
    })

    The Damn.implicit() call returns a promise which resolves to a Damn object, from which you can call all the methods described below.

    Methods

    All these methods are asynchronous and return promises.

    getDailyDeviations(qs)

    Public endpoint

    Returns the list of today's daily deviations:

    damn.getDailyDeviations()
    .then(dailyDeviations => {
      ...
    })

    Parameters:

    • qs (object): additional query parameters (eg. for pagination)

    getNotifications(qs)

    Private endpoint

    Returns the list of current user notifications:

    damn.getNotifications()
    .then(notifications => {
      ...
    })

    Parameters:

    • qs (object): additional query parameters (eg. for pagination)

    getWatchFeed(qs)

    Private endpoint

    Returns the current user's watch feed:

    damn.getWatchFeed()
    .then(feed => {
      ...
    })

    Parameters:

    • qs (object): additional query parameters (eg. for pagination)

    getDeviation(deviationId, qs)

    Public endpoint

    Returns the details of a specific deviation:

    const deviationId = 12345
     
    damn.getDeviation(deviationId)
    .then(deviation => {
      ...
    })

    Parameters:

    • deviationId (string): the deviation id.
    • qs (object): additional query parameters (eg. for pagination)

    galleryAll(username, qs)

    Public endpoint

    Returns the list of a user's deviations:

    const username = 'sdqlm'
     
    damn.galleryAll(username)
    .then(deviations => {
      ...
    })

    Parameters:

    • username (string): optional username, defaults to current user
    • qs (object): additional query parameters (eg. for pagination)

    galleryFolder(folderId, username, qs)

    Public endpoint

    Returns the list of a folder's deviations (all user's deviations if no folderId is given):

    const folderId = 12345
     
    damn.galleryFolder(folderId)
    .then(deviations => {
      ...
    })

    Parameters:

    • folderId (string): optional folderId
    • username (string): optional username, defaults to current user
    • qs (object): additional query parameters (eg. for pagination)

    galleryFolders(username, qs)

    Public endpoint

    Returns the list of an user's gallery folders:

    const username = 'qpsdlq'
     
    damn.galleryFolders(username)
    .then(deviations => {
      ...
    })

    Parameters:

    • username (string): optional username, defaults to current user
    • qs (object): additional query parameters (eg. for pagination)

    userFriends(username, qs)

    Public endpoint

    Returns a list of the user's watched friends:

    const username = 'qpsdlq'
     
    damn.userFriends(username)
    .then(friends => {
      ...
    })

    Parameters:

    • username (string): username to search for friends of
    • qs (object): additional query parameters (eg. for pagination)

    userFriendsSearch(username, query)

    Public endpoint

    Returns a list of the user's watched friends:

    const username = 'qpsdlq'
    const query = 'bob'
     
    damn.userFriendsSearch(username, query)
    .then(friends => {
      ...
    })

    Parameters:

    • username (string): username to search for friends of
    • query (string): Search query (min length: 1)

    placebo()

    Public endpoint

    Implementation of DA's placebo route. Use it to check you access token validity. Or better yet, use checkAccessToken()!

    damn.placebo.then(placebo => {
      ...
    })

    checkAccessToken()

    Check the validity of your access token, returns a boolean.

    damn.checkAccessToken.then(validToken => {
      ...
    })

    Todo

    • Use Node.js v4.0.0 and ES6 features
    • Automate token refresh
    • Setup linter
    • Add access to the following routes:
    • /user/friends/{username} Get a list of watched friends
    • /user/friends/search Search a list of watched friends
    • /deviation/{deviationid} Fetch a deviation
    • /deviation/content Fetch full data that is not included in the main deviation object
    • /browse/morelikethis Fetch MoreLikeThis result for a seed deviation
    • /browse/newest Browse newest deviations
    • /browse/popular Browse popular deviations
    • /browse/hot Browse whats hot deviations
    • and all others routes ?
    • Revoke access / logout
    • Find a way to implement Authorization Code as an authentication method
    • Support for pagination params

    Install

    npm i damn

    DownloadsWeekly Downloads

    1

    Version

    0.2.0

    License

    MIT

    Last publish

    Collaborators

    • as0n