Portatext NPM | npm.io

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.