Badgr-client

Work In Progress: not much to see for now.

A nodejs client for the badgr-server API.

The main goal is to use this client in PaperBadger, so the bulk of the work will focus on the needs of that particular project. At some point, the library will be extended to support the full Badgr API.

What works for now

• Authorisation through user name and password (only method supported by the Badgr API).
• List all badges
• Issue badges to a recipient (email as Id)
• List all instances of a badge by issuer
• List all badges issued to a particular recipient (by ORCID)
• List all badges issued for a particular paper (by evidence doi url)

What needs to be done?

The bulk of the work is stated in #7.

Development

Fork and clone

Fork a repo as per github instructions and then clone with (make sure to swap YOUR_USER_NAME with your real github username):

git clone [email protected]:YOUR_USER_NAME/badgr-client.git

Main branch - dev

Note that the main branch is dev and not master. All work will eventually be merged into master, but dev is the working branch, while master will be used to publish to nmp.

Tests

Mocha is the test framework used for this project, and chai is the assertion library. Run all tests with npm test.

Unit tests can be run with npm run test:unit.

Testing will automatically lint and stop if code style does not pass.

Note that you will need to copy the default.env file into an .env file in order to provide authentication details for a Badgr user and server URL.

Easy badgr-server install

For an easy way to install badgr-server, you can use this Dockerfile.

Code Style

This project follows most of the guidelines in the mofo-style package. Some of the rules have been modified because this is not a front-end ES6 project.

Linting will be run automatically with some other tasks (such as testing), but can be invoked by itself with npm run lint.

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

Install & Usage

Note that there's no npm package yet, so you can npm link if you want to use it in a demo app

The easiest way to see how to use the library is to look into the integration tests in badge_methods.js

Client setup & API calls

The main example in tests so far is:

    it('should return data when calling all badges', function (done) {
      var client = new Index(apiEndpoint, goodTestAuth);

      client.getAllBadges(function (err, data) {
        expect(err).to.be.null;
        expect(data).not.to.be.undefined;
        expect(data[0].created_at).not.to.be.undefined;
        done();
      });
    });

where apiEndpoint is a valid url to a badgr-server instance, and goodTestAuth is in the form: { username: '[email protected]', password: 'xxx'}.

Concerns and things to watch out for

Because this library is being created for PaperBadger, some abstractions from that project may be leaking into the library. For instance, the evidence field is used to contain a paper doi url, and the method is currently called getBadgeInstancesByEvidence, although getBadgeInstancesByPaper would make more sense in PaperBadger. This would not make sense in a generic badges context, though. Another example is using references to DOI and ORCID within the tests. Those tests should not fail even if the data is not available, but it ties the library to the PaperBadger domain.

The library should be as generic as possible.

Jos - May 2o16