Atrium-node NPM

atrium-node

Atrium Node is a package designed to assist with connections to the exposed SDK of CDVI Atrium Controllers.

You can read more about the CDVI SDK here

Getting Started

Install the atrium-node package via npm:

npm install --save-dev atrium-node

Connecting

To connect to your Atrium controller, all you need to do is instantiate a new AtriumController class object.

import { AtriumController } from 'atrium-node';

const controller = new AtriumController(`http://localhost:2000`, "username", "password"/**, { ...additionalOptions }*/);

Retrieving Data

Data can be retrieved using atrium-node by using the .getByIndex() function on the AtriumController object combined with the data type you desire.

NOTE: Only "cfg" data types are available right now.

import { AtriumController } from 'atrium-node';
import { User, Card, AccessLevel } from 'atrium-node/prototypes';

const controller = new AtriumController(`http://localhost:2000`, "username", "password");
const users = await controller.getByIndex(User, 0, 10);
const cards = await controller.getByIndex(Card, 0, 10);
const accessLevels = await controller.getByIndex(AccessLevel, 0, 10);

Additionally, there is another function called .getAll(prototype) which will get all records for that data type. However, this function is slow and experimental, as it will consistently call and grab more data from the Controller until the number of total number of record slots pulled is less than the batch size that was specified in the constructor. The final array of records returned gets free slots filtered out, so all you receive are actual used/existing objects of that data type.

Inserting Data

Data can be inserted into the Controller by using the .insert(...prototypes) function with a provided AtriumObject object that was created from one of the prototypes imported from atrium-node/prototypes.

Each prototype takes an object that represents its data.

Certain prototypes will have additional functions on them that can help you tie prototypes together and preparing data upon insertion.

For example, User and Card will have respective .assignCard and .assignUser functions.
These types of functions will ensure that the Id is set whenever the primary Id has been assigned, so long as their "id" property does not exist in the record that is passed into their respective constructor.

Card will also have functions like .set26BitCardNumber(familyNumber, cardNumber) and so on for the respective card numbers.

import { AtriumController } from 'atrium-node';
import { User, Card, AccessLevel } from 'atrium-node/prototypes';

const controller = new AtriumController(`http://localhost:2000`, "username", "password");

let johnDoe = new User({
    firstName: "John",
    lastName: "Doe"
});
// note: you don't need to use the "new" keyword here...
let janeDoe = User({
    firstName: "Jane",
    lastName: "Doe"
});

let johnDoeCard = Card({
    displayName: "John Doe Card"
});
let janeDoeCard = Card({
    displayName: "Jane Doe Card"
});

johnDoe.assignCard(johnDoeCard);
janeDoe.assignCard(janeDoeCard);

[johnDoe] = await controller.insert(johnDoe);
[johnDoeCard, janeDoeCard] = await controller.insert(johnDoeCard, janeDoeCard);
[janeDoe] = await controller.insert(janeDoe);
// johnDoe and janeDoe will have their respective `id` properties assigned.
// johnDoeCard and janeDoeCard will have their related  `userId` properties assigned and the Controller will also
//   reflect those relationships (no matter the order of insertion)

Updating Data

Data can be updated in the Controller by using the .update(...records) function, which behaves exactly like the .insert() function.

import { AtriumController } from 'atrium-node';
import { User, Card, AccessLevel } from 'atrium-node/prototypes';

const controller = new AtriumController(`http://localhost:2000`, "username", "password");

let johnDoe = new User({
    firstName: "John",
    lastName: "Doe"
});
// note: you don't need to use the "new" keyword here...
let janeDoe = User({
    firstName: "Jane",
    lastName: "Doe"
});

[johnDoe, janeDoe] = await controller.insert(johnDoe, janeDoe);

johnDoe.firstName = "Johnny";
janeDoe.lastName = "Dough";

[johnDoe, janeDoe] = await controller.update(johnDoe, janeDoe);

Deleting Data

Data can be deleted in the Controller by using the .delete(...records) function, which behaves exactly like the .insert() and .update() functions.

import { AtriumController } from 'atrium-node';
import { User, Card, AccessLevel } from 'atrium-node/prototypes';

const controller = new AtriumController(`http://localhost:2000`, "username", "password");

let johnDoe = new User({
    firstName: "John",
    lastName: "Doe"
});
// note: you don't need to use the "new" keyword here...
let janeDoe = User({
    firstName: "Jane",
    lastName: "Doe"
});

[johnDoe, janeDoe] = await controller.insert(johnDoe, janeDoe);
[johnDoe, janeDoe] = await controller.delete(johnDoe, janeDoe);
// this function still returns the records back, but they will be deleted from the Controller.

Miscellaneous

This section covers a few extra utility functions that exist alongside the AtriumController class.

consumable (API consumption)

Data retrieved from the AtriumController object will be as class objects themselves, as they are required to be to communicate properly with the underlying API that handles the XML serialization.

However, in most API's, the data being consumed is expected to be of something that can be serialized appropriately. A class object, unfortunately, cannot be serialized.

Therefore, the function consumable() is available in the atrium-node/util directive to convert your Prototype class objects into their appropriate object models, which can then be consumed by your API.

Example in Node.js express:

import { AtriumController } from 'atrium-node';
import { Card } from 'atrium-node/prototypes';
import { consumable } from 'atrium-node/util';
// ... express imports and initialization

const ctrl = new AtriumController(/** ... */);

app.get('/', (req) => {
    req.json(consumable(await ctrl.getByIndex(Card, 0, 10)));
});

EnlightedDate (easy dates)

EnlightenedDate is a cringey attempt at making an extended Date method that exposes a few extra functions to it. Each of the functions are provided to assist with creating and updating activation and expiration dates within the controller.

The functions consist of:

.addMilliseconds(numMs): Adds numMs milliseconds to the Date in UTC.
.addSeconds(numSeconds): Adds numSeconds seconds to the Date in UTC.
.addMinutes(numMins): Adds numMins minutes to the Date in UTC.
.addHours(numHours): numHours hours to the Date in UTC.
.addDays(numDays): Adds numDays days to the Date in UTC.
.addWeeks(numWeeks): Adds numWeeks weeks to the Date in UTC.
.addMonths(numMonths): Adds numMonths months to the Date in UTC.
.addYears(numYears): Adds numYears years to the Date in UTC.

Example:

import { today, now, neverExpires, EnlightenedDate } from 'atrium-node/util';

const eDate = new EnlightenedDate();
eDate.addDays(14); // Assume this is called at 10/01/2023 03:32:44, result: 10/15/2023 08:32:44

// alternatively, to get today's date you can use the utility function:
const today = today();
today.addDays(14).addHours(6); // Assume this is called at 10/01/2023 03:32:44, result: 10/15/2023 06:00:00

// or now
const now = now();
now.addDays(10).addHours(5); // Assume this is called at 10/01/2023 03:32:44, result: 10/11/2023 08:32:44

// or if the object should never expire
const never = neverExpires();

Prototypes

CDVI's Atrium Controller SDK handles many different prototypes, and while many are still not available due to them being incomplete, you can find most of them in the /prototypes directive.

If you wish to contribute and complete some prototypes, refer to one of the already completed prototypes, it will mostly be copy-and-paste, but there are a couple things you would have to complete yourself.

You can find information about each data type in the Atrium SDK Demo software.

Crypto

The cryptography used is found in the sub-package atrium-node/crypto, which will consist of three functions:

RC4.encrypt(key, plaintext): Encrypts plaintext using the RC4 algorithm given the key.
RC4.decrypt(key, ciphertext): Decrypts ciphertext using the RC4 algorithm given the key.
MD5(text): Hashes text using the MD5 hashing algorithm.