anyfetch

AnyFetch API wrapper for Node.js

You'll only be interested in this package if you want to create client applications for AnyFetch.

If you're interested in creating a Hydrater or a Provider, you may find AnyFetch Hydrater Library and AnyFetch Provider Library more high level, and easier to work with.

This npm package makes communicating with the AnyFetch servers easy for clients. Check out the full API documentation.

Basic usage example

var AnyFetch = require('anyfetch');
 
var anyfetchBasic = new AnyFetch('LOGIN', 'PASSWORD');
// OR
var anyfetch = new AnyFetch('TOKEN');
 
anyfetch.getUser(function(err, user) {
  console.log('Hello, my name is ' + user.name);
};

Access authentication

AnyFetch delivers long lived access_token, so you don't need to use a refresh_token.

Both Basic and Bearer authentication schemes are supported. The getToken method makes it easy to retrieve a token from the user's credentials. If you're using Bearer authentication, the token in use is available in the property anyfetch.accessToken.

var AnyFetch = require('anyfetch');
 
var anyfetchBasic = new AnyFetch('LOGIN', 'PASSWORD');
 
// Retrieve token from credentials (GET /token)
anyfetchBasic.getToken(function(err, res) {
  if(err) {
    throw err;
  }
 
  anyfetch = new AnyFetch(res.body.token);
  // We now access the Fetch API using Bearer authentication
  // You can get back the token by accessing `anyfetch.accessToken`
  console.log('We are using the token ' + anyfetch.accessToken);
};

OAuth

The getAccessToken static function helps you obtain an access_token during the OAuth flow.

AnyFetch.getAccessToken('APP_ID', 'APP_SECRET', 'OAUTH_VERIFICATION_CODE', function(err, accessToken) {
  var anyfetch = new AnyFetch(accessToken);
});

Basic endpoint to function mappings

This library provides a function per API endpoint. A full reference card is available.

We adopt the following naming convention:

verbEndpointName(function(error, result) {})

Callbacks are expected to be of the form: function(err, result). result is a Response object from Superagent. Note that some endpoints yield a result with empty body (e.g. POST /company/update).

Examples:

• getUsers(cb) will call GET /users
• postCompanyUpdate(cb) will call POST /company/update
• postUser({ email: '[e-mail]' }, cb)
• deleteCompanyReset(cb) will call DELETE /company/reset
• deleteCompanyReset(cb, { force: true }) will call DELETE /company/reset?force=true
• deleteToken(cb) will call DELETE /token

Example usage:

var anyfetch = new AnyFetch('TOKEN');
anyfetch.getDocuments({ search: 'John' }, function(err, res) {
  if(err) {
    throw err;
  }
  var docs = res.body;
  console.log('Got these documents:', docs)
});

Some functions expect an id or identifier:

• getDocumentById(id, cb) will call GET /documents/{id}
• getDocumentByIdentifier(identifier, cb) will call GET /documents/identifier/{identifier}

Some other endpoints are expressed relative to a document. For example, GET /documents/{id}/raw refers to the document with id {id}. For the sake of clarity, we provide the following two-steps call syntax:

• getDocumentById(id).getSimilar(cb) will call GET /documents/{id}/similar
• getDocumentById(id).getRaw(cb) will call GET /documents/{id}/raw
• getDocumentById(id).postFile(config, cb) will call POST /documents/{id}/file

Note that the first function does not take any callback. It is simply responsible for building the first part of the request, which is then carried out when calling the sub-function.

A full description of the mapping functions is available in api-descriptors.json.

Posting a file associated to a document

Head's up: if you need to post a new document along with a file, see below for the sendDocumentAndFile helper function.

The function getDocumentById(id).postFile(config, cb) expects a config hash containing at least a file key from which to obtain the file. It can be a string (path to the file) or a ReadStream. It can also contains contentType (MIME type) and filename keys.

config can also be passed as a function. In this case, it is invoked with a callback, which must be called with (err, config).

Example usage:

var deliverConfig = function(cb) {
   cb(null, {
      file: fs.createReadStream('path/to/file.png'),
      filename: 'doge.png'
   });
};
 
getDocumentById(id).postFile(deliverConfig, function(err) {
  // Handle error if any
});

Utility functions

anyfetch.js provides higher level utility functions. They cover classic use-cases that would otherwise require several API calls. When possible, calls are grouped in a single batch call.

Batch request

Make several GET calls in a single request. It takes a map associating the endpoint to its parameters.

var pages = {
  '/users': null,
  '/documents': {
    search: 'Marc'
  }
};
anyfetch.batch(pages, function(err, res) {
  // Handle err
 
  var users = res.body['/users'];
  var documents = res.body['/documents'];
});

See GET /batch for details.

Create a subcompany

When creating a subcompany, we usually want to create its first admin, and migrate it into the new subcompany. The function createSubcompanyWithAdmin allows you to do this automatically. The created user will be an admin in the new subcompany.

Your callback is called with err, subcompanies (info about the newly created company) and admin (info about its admin).

var subcompany = {
  name: 'the_fake_subcompany',
  hydraters: [
    'http://plaintext.hydrater.anyfetch.com/hydrate',
    'http://pdf.hydrater.anyfetch.com/hydrate',
  ]
};
var admin = {
  email: '[e-mail]',
  name: 'Chuck Norris',
  password: 'no_need'
};
anyfetch.createSubcompanyWithAdmin(subcompany, admin, function(err, company, admin) {
  console.log('Company ' + company.id + ' has been created, with ' + admin.id + ' as its admin');
});

Get information about the current user

This function allows you to retrieve the user's info from its credentials (login / password or token).

anyfetch.getUser(function(err, user) {
  console.log('Hello, my name is ' + user.name);
};

Send a document with a file in a single call

When writing an AnyFetch provider, it is very common to need to create a document on the AnyFetch API, and post an associated file right away. This function makes it easy to do just that:

var doc = {
  document_type: 'file',
  data: {
    foo: 'some_string'
  },
  metadata: {
    some_key: 'some random sentence'
  }
};
// We'll simply upload from filename
var fileConfig = {
  file: __dirname + '/../test/samples/hello.jpg',
  filename: 'hello_image',
  contentType: 'image/jpeg'
};
 
anyfetch.sendDocumentAndFile(doc, fileConfig, function(err, doc) {
  console.log('The document has been posted');
});

For details about the supported fileConfig options, see the postFile function above.

Manager endpoints

A few endpoints of the AnyFetch Manager are available in anyfetch.js for convenience.

• The first example is getToken(cb), described above.

• postAccountName(accountName, cb) allows you to associate an account name to the access token currently in use. It can only be used with Bearer auth.

• getAvailableProviders(options, cb) allows you to obtain a list of all the available providers. The options object can have booleans trusted and featured to restrict the list. options can be omitted. Example:

  var anyfetch = new AnyFetch('access_token');
  anyfetch.getAvailableProviders({ trusted: true }, 'my_awesome_account_name', function(err, res) {
    console.log('Here are all the trusted providers:');
    console.log(res.body);
  });

Overriding target URLs

By default, all methods target the production URLs: https://api.anyfetch.com and https://manager.anyfetch.com respectively. There are two ways to override that:

• For all instances:

  var AnyFetch = require('anyfetch');
  AnyFetch.setApiUrl('http://localhost:3000');
  AnyFetch.setManagerUrl('http://localhost:3000');

• For one instance only:

  var AnyFetch = require('anyfetch');
  var anyfetch = new AnyFetch('TOKEN');
  anyfetch.setApiUrl('http://localhost:3000');
  anyfetch.setManagerUrl('http://localhost:3000');

It is very useful when writing tests and want to take advantage of the mocking server described below.

Test framework

anyfetch.js provides a ready-to-run mock server based on Restify. It may be useful to test apps that use the AnyFetch API.

The mock server is created with AnyFetch.createMockServer() and started with server.listen(port, cb). It is a simple Restify server. Once the server is running, override the AnyFetch API url to make it point to your localhost with anyfetch.setApiUrl(url). If you're using the OAuth helper method AnyFetch.getAccessToken, override the manager URL as well with AnyFetch.setManagerUrl(url). Indeed, the mock server also plays the role of manager.

Example: starting the mock server on port 1337

var AnyFetch = require('anyfetch');
var server = AnyFetch.createMockServer();
 
var port = 1337;
var apiUrl = 'http://localhost:' + port;
server.listen(port, function() {
  console.log('AnyFetch mock server running on ' + apiUrl);
  AnyFetch.setApiUrl(apiUrl);
  AnyFetch.setManagerUrl(apiUrl);
 
  done();
});

Mocks

The mock server will serve static JSON files from the folder node_modules/anyfetch/lib/test-server/mocks. You can tailor them to your need. You can generate those JSON files at any time by:

1. Setting the LOGIN and PASSWORD environment variables to your Fetch API credentials
2. Running node node_modules/anyfetch/bin/make-mocks.js

Overriding

At any point, you can specify which JSON content to serve for any endpoint using the following methods:

• server.override(verb, endpoint, json) to start serving your custom JSON for this endpoint
• server.restore(verb, endpoint) to go back to the default built-in response
• server.restore() to restore all previously overriden endpoints

Note that these will work even if you try to override an endpoint which does not exist by default. It is useful in testing, for example if you have an odd request to send to a specific route on another API.