node-sdk

Official NodeJS Client for the PortaText API.

Documentation

• Autogenerated documentation for this source can be found in the doc directory.
• The endpoint tests should also serve as good doucmentation on how to use the API.
• General PortaText documentation (including the REST API) can be found at the PortaText wiki.

Installing

Add this library to your package.json configuration:

  "dependencies": {
    "portatext": "latest"
  }

Basic use

Getting a client instance

The first thing is to get a Client instance, for example the Curl implementation:

var portatextMod = require('portatext');
var portatext = new portatextMod.ClientHttp();

(Optional) Set your logger

You can optionally set a Console compatible logger:

portatext.setLogger(console);

By default, the client will use the NullLogger.

Authenticating

You can authenticate to the endpoints by using your API key or your username/password. This translates to either doing this:

portatext.setApiKey(apiKey);

Or this:

portatext.setCredentials(username, password);

When you specify a username and password instead of an api key, the sdk will automatically login and get a session token when needed.

Using the endpoints

All the API commands can be found in the command/api directory. The client offers a way to instantiate them by just calling them by their name.

Quick example

As an example, to create a template, you would do:

client
  .templates()                       // Get an instance of the Templates endpoint.
  .text("The text of my template")
  .description("My first template")
  .name("template1")
  .post()                            // Call the Templates endpoint with a POST.
  .then(function (result) {
    // Handle result...
  })
  .catch(function (err) {
    // Handle error...
  });

To get a template by id:

client.templates().id(45).get().then(function (result) { .... });

Or, to get all the templates:

client.templates().get().then(function (result) { .... });

The result

Calling an endpoint will return a Promise. On fulfillment, a result object is returned (see below for how to handle it). On rejection, you can get a string or a result object (in case the request was made but the server returned one or more errors in its response, for example if a field was missing or different than what was expected).

Testing for success

if (result.success) {
  ...
}

Getting error strings back from the server

if (result.errors) {
  result.errors.forEach(function (error) {
    ...
  });
}

Getting data back from the server

if (result.success) {
  var data = result.data;
}

Developers

This project uses standard npm scripts. Current tasks include:

• test: Runs Mocha tests.
• jsdoc: Runs JSDoc3.
• eslint: Runs ESLint.
• coverage: Runs the tests and then Instanbul to get a coverage report.
• build: This is the default task, and will run all the other tasks.

Running a phing task

To run a task, just do:

npm run build

Contributing

To contribute:

• Make sure you open a concise and short pull request.
• Throw in any needed unit tests to accomodate the new code or the changes involved.
• Run npm run build and make sure everything is ok before submitting the pull request (make eslint happy).
• Your code must comply with the Javascript Standard Style, ESLint should take care of that.
• If your code is accepted, it will belong to PortaText and will be published under the Apache2 License.

License

The source code is released under Apache 2 License.

Check LICENSE file for more information.