Servant SDK for Node.js

A simple library for interacting with the Servant API in your Node.js application.

Check out the Servant MEAN Boilerplate application to see an example of how to use this SDK as well as to help you rapidly build Servant Application.

Features

• Simple Servant Connect Authorization: Handle server-side authorization in only a few lines of code.
• Archetype Instantiation: Create instances of Archetype Objects already filled with all properties available
• Archetype Validation: Validate Archetype Objects locally, without having to send them to Servant.
• Archetype Methods: Save, Update and Query Archetype Records easily with tons of helper methods

Testing

Run npm test

How To Use

Register a Servant Application in the Servant Dashboard. Select 'Auth Code (Server App)' for Oauth2 Flow.

Require:

var Servant = require('servant-sdk-node')({ application_client_id: 'APPLICATIONCLIENTID', application_client_secret: 'APPLICATIONSECRET' });

Connect Authorization: In the Servant Dashboard, you are able to select whether your app is a browser-based application or a server-based application. If you plan on building a server-based application, this Node SDK will help you connect to people's servants with only a couple lines of code.

• Register your application in the Servant Dashboard. Under Oauth2 Flow select "Auth Code (Server App)".

• Specify a Redirect URL for your application. When a user clicks "Connect Servant", they are taken to an authorization window for your application. When they authorize they are redirected to the redirect_url you specify here.

• In your application, make sure you declare a route for the redirect_url. In that route, use the Servant.exchangeAuthCode() method for new users. This exchanges an authorization code for a new

   var servantConnectCallback = function(req, res) {
        // If a code parameter (authorization code) is included, the User is connecting for the first time
        if (req.query.code) {
             // Exchange the authorization code for refresh and access token via this SDK method
            Servant.exchangeAuthCode(req.query.code, function(error, servant_tokens) {
            // Returns Refresh Token and Access Tokens and redirect the user to your app's dashboard
            });
        }
        // If refresh_token was included in the parameters, the User has already authenticated and is using the Connect button to log into your application
       if (req.query.refresh_token) {
           // Save the user's access token and redirect them to your app's dashboard
   }
  

If you want to learn more about the Oauth2 Authorization Code flow in general, check out this great article by Aaron Parecki.

Servant.getUserAndServants(access_token, callback) Fetches the account user and their Servants which your application has permission to.

Servant.getUserAndServants(access_token, function(error, response) {

});

Servant.queryArchetypes(access_token, servantID, archetype, criteria, callback) Queries records of an Archetype on a Servant. This method can take most MongoDB queries. Format query criteria like this:

var criteria = { query: { price: 0 }, sort: {}, page: 1 };   

Servant.queryArchetypes(access_token, servantID, 'product', criteria, function(error, response) {
    console.log(error, response);
});

Not including query criteria will simply fetch the 10 most recent records of the specified archetype.

Iterate the page integer to paginate through results.

Servant.instantiate(archetype, callback) Creates a new instance of an Archetype.

var contactInstance = Servant.instantiate('contact');

Servant.validate(archetype, instance, callback) Validates an instance of an Archetype against the Archetype's rules (e.g. character limits, max items, etc.). The instance will pass through without error if it is valid.

Servant.validate('contact', contactInstance, function(error, contact) {
    
});

Servant.saveArchetype(access_token, servantID, archetype, instance, callback) Creates or Updates an Archetype record on a Servant. If the instance has an "_id" property, this will attempt to update an existing record. If the instance has no "_id" attribute, a record will be created.

Servant.saveArchetype(access_token, servantID, 'contact, contactInstance, function(error, response){

});

Servant.showArchetype(access_token, servantID, archetype, archetypeID, callback) Shows a record of an Archetype from Servant.

Servant.showArchetype(access_token, servantID, 'product', archetypeID, function(error response) {
    console.log(error, response);
});

Servant.deleteArchetype(access_token, servantID, archetype, archetypeID, callback) Deletes a record of an Archetype from Servant.

Servant.deleteArchetype(access_token, servantID, 'product', archetypeID, function(error, response) {
    console.log(error, response);
});