Integrating a key/credentials auth service with the Flow XO SDK.

index.js

'use strict';

var sdk = require('flowxo-sdk'),
  request = require('request'),
  url = require('url');

var service = new sdk.Service({
  serviceRoot: __dirname,
  name: 'HipChat',
  slug: 'hipchat',
  auth: {
    
    // We describe the fields that we want to collect.  Sometimes
    // just an auth key or a username & password, and sometimes
    // extra fields such as the account's hostname too.
    // In this case, we just need an 'Auth Token'.
    
    type: 'credentials',
    fields: [{
      type: 'text',
      key: 'auth_token',
      label: 'Auth Token',
      
      // Give a good description so the user knows exactly where to get an
      // auth token from.
      
      description: 'To create a token in HipChat, click your profile in the top ' +
        'right-hand corner, click \'Account settings\', then \'API access\'.  Choose a ' +
        'label for your token and select at least \'Send Message\', \'Send Notification\', ' +
        '\'View Messages\' and \'View Room\' scopes. Finally, copy your token into here.',
      required: true
    }]
  },
  scripts: {
    ping: require('./ping')
  }
});

// We create a helper method to help us to make API
// calls and handle any errors.

service.request = function(options, done) {
  var opt = {
    url: url.format({
      protocol: 'https',
      host: 'api.hipchat.com',
      pathname: '/v2' + options.endpoint,
      query: options.query || {}
    }),
    headers: {
      Authorization: 'Bearer ' + options.token
    },
    method: options.method || 'GET',
    json: options.json || true,
    timeout: 30000
  };

  request(opt, function(err, res, body) {
    if(err) {
      // Retryable error - possibly network related.
      return done(err);
    }

    if(res.statusCode >= 200 && res.statusCode <= 299) {
      // 2xx means it was a success!
      return done(null, body);
    }

    if(res.statusCode === 401) {
      // 401 is an auth error.
      return done(new sdk.Error.AuthError('There was an authorization error, please connect again.'));
    }

    if(res.statusCode >= 400 && res.statusCode <= 499) {
      // Any other 4xx is a client error.
      // Return a ServiceError - don't run again.
      return done(new sdk.Error.ServiceError(body.error.message));
    }

    // Some other, retryable error occurred.
    return done(new Error(res.statusCode + ' ' + body));
  });
};

module.exports = service;

ping.js

'use strict';

// Our ping.js script is used to test whether the
// credentials the user gave are valid.
// Expects either done(err) or done().

module.exports = function(options, done) {

  var opt = {
    endpoint: '/oauth/token/' + options.credentials.auth_token,
    token: options.credentials.auth_token
  };

  this.request(opt, done);
};

run.js

'use strict';

// An example of how to use the credentials to
// make a call to our API through our service.request()
// helper method in index.js.
// Simplified - a real run.js would at least need
// some input validation too.

module.exports = function(options, done) {
  var opt = {
    endpoint: '/room/' + options.input.room_id + '/message',
    token: options.credentials.auth_token,
    method: 'POST',
    json: options.input
  };

  this.request(opt, done);
};