The library allows for completely offline operation of the Olaii Cashless system.
Current version supports only NTAG213 cards in conjunction with ACR1222L reader. For more details about the implementation please refer to the internal documentation of the Offline Card Operation stored in the Company Document Storage.
Library currently supports the following functionality:
For reader specific commands please look at the node-acr1222l library documentation located at: https://github.com/Olaii/node-acr1222l
To initialize the library you will need to perform the following:
Code sample:
const master_pwd = Buffer([0xff, 0xfe, 0xff, 0xfe]);
const conf_year = 0x02;
const act_fee = 100; // 1 eur
await olaiiNFC.initialize(report_error_cb, pcsc_error_cb, master_password=master_pwd, current_conf_year=conf_year, activation_fee=act_fee, debug=true);
Report callback function is invoked when a balance store procedure fails or succeeds after a retry. The function will receive at input an object, that will contain the following properties:
These properties should be logged to the application journal and possibly the master server, to enable the administrators a look at the error rate and if certain errors were not fixed.
Possible types of the message are:
Master password is set by the master server for each and every campaign. Master password is 32 bits long (4B), and should be passed upon the library initialization.
Configuration year is also set by the master server and is a single integer smaller than 128 (1B). If the card configuration year does not match the passed parameter, the card will be reformatted with balance 0 upon first deposit. Bill and withdraw functions will raise an error CARD_NOT_YET_ACTIVATED.
Here we will briefly describe the application flow that you should follow. Since the NTAG213 does not support tearing protection, the retry policy should be implemented on the application level and thus you must follow theese instructions carefully!
Offline operation withdraw is slightly different than the one of online model.
List of library errors and description of error object.
The library can throw several errors that must be handled correctly. First, to check if the error is library specific or a regular excpetion you must check if the error contains the status property.
...
} catch(err) {
if(err.status && err.status==='BALANCE_STORE_FAILED') {
...
List of application level errors is the following:
Some errors can happen only if you issue calls to the underlying reader library, but for clarity we should handle all of them in the application.
Short description of the deposit operation and possible errors and how they should be handled.
Parameter description:
Function name: performDeposit
If we are depositing to a fresh card, the library will detect that and try to configure the card for current year. If the configuration fails, card is removed or any other error it will throw CONFIGURATION_FAILED error.
After configuration check the library will perform read card operation which may result in READ_FAILED error.
The function will perform validation of the current configured year. If it doesn't match it will try to store balance 0 and current configuration year to the card. At this point it can raise errors:
Next the library will try to parse the card balance and perform the deposit.
Should the function call throw error BALANCE_STORE_FAILED the application must switch to retry mode. Meaning it should reissue the call with is_retry set to true.
Simple example of the retry logic (does not handle all the errors...):
async function deposit(amount, hash, is_retry) {
await olaiiNFC.writeToLCD('Tap card please', 'Deposit ' + amount);
const ndef_obj = await olaiiNFC.readNDEF();
await olaiiNFC.performDeposit(ndef_obj.uuid_bytes, ndef_obj.ndef, amount, hash, is_retry);
await olaiiNFC.clearLCD();
const hash = Math.floor(Math.random()*128);
try {
await deposit(1000, hash, false);
} catch(err) {
if(err.status && err.status==='BALANCE_STORE_FAILED') {
console.log('Failed to store balance. Please retry...');
await deposit(1000, hash, true);
} else {
throw err;
}
}
Should the first deposit be smaller than activation fee, the library will throw DEPOSIT_TO_SMALL error.
The function will return object with properties:
If we are issuing refund of the invoice, the library will basically call performDeposit with the refund amount.
Parameter description:
Function name: performBill
Bill is very similar to the deposit in terms of the flow. Therefore this segment will only outline the differences, that you should be aware of.
Also please note that, once again all amounts must be positive integers. So for example:
Other possible errors bill might throw are:
Upon BALANCE_STORE_FAILED, the application must switch to retry mode.
Withdraw is a wrapper around performBill. It's functionality and parameters are the same.
To check the card balance all you have to do is obtain the card uuid and serial number through the readNDEF function.
Then you should call the getBalance like the example shows below:
const ndef_obj = await olaiiNFC.readNDEF();
const balance = await olaiiNFC.getBalance(ndef_obj.uuid_bytes, ndef_obj.ndef);
console.log('Current balance:', balance);
FAQs
Olaii NFC Tools for Offline transactions
The npm package olaii-nfc receives a total of 0 weekly downloads. As such, olaii-nfc popularity was classified as not popular.
We found that olaii-nfc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.