Amatino API v0.0.18 [Heavily Breaking Changes]

A new version of the Amatino API has been deployed. 0.0.18 contains breaking changes – Any code interfacing with versions below 0.0.18 will not work with 0.0.18.

0.0.18 modifies the way HMAC signatures are computed. JSON bodies are no longer included in signature computation. Their inclusion was causing intermittent issues for customers: Seemingly at random, requests would be met with 401 - Not Authenticated responses.

The inclusion of JSON bodies in HMAC computation was, in hindsight, a poor decision. By definition, JSON object key/value ordering is indeterminate. If a key/value pair happens to be parsed in a different order on either side of the client / API connection, the request would fail.

Along with API 0.0.18, the following new client libraries are available:

Each of these libraries supports API 0.0.18.

We never want to make breaking changes like this. We understand how frustrating it is to have integrations break, and apologise profusely. While Amatino is in an “alpha” state (pre v1.0.0), we will make these changes as rarely as possible. After v1.0.0, breaking changes will only be made with prior versions remaining online.

Amatino JS 0.0.14 Released

A tiny update has been released for Amatino’s Node library.  0.0.14 fixes a silly bug in the inbuilt Node version enforcement script. The script is run after installation, and was supposed to stop Node versions lower than 10.4 from running Amatino JS. Instead it was stopping versions greater than 11.0 from running it!

Amatino JS 0.0.14 is available on NPM and on GitHub.

Amatino JS 0.0.13 Released

A new version of the Amatino Node.js library is now available. 0.0.13 addresses a big issue that has plagued previous Amatino JS versions, and fixes one other nasty bug:

  • Decode large integers as BigInt rather than hacking them into String
  • Encode Date month properly (previously the previous month was encoded)

When it comes to large integers, JavaScript is a bit of a minefield. Until BigInt came along, JS had no native way of dealing with integers larger than 53 bits.

Internally, the Amatino API only thinks in 64-bit integers and arbitrary-precision numbers. Floats & lower-width integers are absent.

These 64-bit integers flow out into the public domain as IDs of various objects. For example, Session IDs and User IDs are random 64-bit integers. If your Entity is extremely large, you might also encounter them as IDs for Transactions.

It is therefore critical that any Amatino client library be able to understand 64-bit integers. So what to do with JavaScript, whose native number type is 53 bits wide? At first, Amatino JS translated them to String, and sent them back to the API as JSON Strings. This was a huge, awful hack involving a flakey Regular Expression.

Surprise surprise, this caused problems for customers. We are very sorry for that. 0.0.13 solves the problem by taking advantage of the “new” native BigInt type. BigInts arrived in Google V8 version 6.7, have been available in Node since version 10.4.

Consequently, Node.js 10.4 is now the minimum required version for a project that includes Amatino JS.

Because JavaScript wants to be a constant barrel of laughs, the native JSON library cannot serialise or deserialise BigInt. We therefore owe big thanks to Andrey Sidorov, whose MIT licensed json-bigint project we adapted to handle the relevant JSON operations.

Installation & Usage

You can install Amatino JS via NPM. For more information about NPM, check out

$ npm install amatino

Amatino classes may then be accessed by requiring Amatino:

const Amatino = require('Amatino'); Amatino.Transaction.create(...);

If you already have Amatino JS installed, you can update it by executing:

$ npm update Amatino

Take care – This operation may not update the Amatino version number in package.json. You may need to change that manually.

Amatino JS 0.0.12 Released

Amatino’s Node.js library has receive a big ‘ol update. 0.0.12 lifts Amatino JS out of bare-bones alpha territory. New classes allow you to build accounting & finance functions into Node.js applications.

0.0.12 is by no means a ‘feature complete’ or beta release. Most Amatino services still lack dedicated classes. However, it is a major step towards such a release. To see plans for 0.0.13 and beyond, check out the newly populated GitHub issue tracker, and Projects page within which future work is organised into planned releases.

New capabilities

Amatino JS now offers the following classes:

Allowing you to easily access and manipulate the `Primary Objects’ discussed in Amatino’s HTTP documentation.

Amatino Javascript Documentation

This release includes the first version of Amatino’s Javascript documentation. The docs are hosted on the Amatino JS GitHub wiki. They provide comprehensive reference for all properties and methods, and example code.

Screenshot from the Amatino JS docs Account page

Installation & Usage

You can install Amatino JS via NPM. For more information about NPM, check out

$ npm install amatino

Amatino classes may then be accessed by requiring Amatino:

const Amatino = require('Amatino');

The Amatino JS Readme has been updated with a getting-started guide, including example code showing you how to start utilising Amatino services. Check it out on the Amatino JS GitHub page.

What’s next?

Check out the Amatino JS Projects page to see the roadmap for future releases. These plans are totally in flux: Feel free to contact me via Twitter (@hugh_jeremy), email (, or on the Amatino discussion forums, and tell me what you would like to see next.

Special thanks must go to James Robb ( Over the past few weeks, James has provided substantial and invaluable advice about how to move the Amatino JS project forward. Thank you James!

– Hugh