basiq-sdk-nodejs

1.1.3 • Public • Published

Basiq.io Node.js SDK

This is the documentation for the Node.js SDK for Basiq.io API

Introduction

To view the API docs, click here.

The SDK is organized to mirror the HTTP API's functionality and hierarchy. The top level object needed for SDKs functionality is the Session object which requires your API key and may require API version to be instantiated. You can create a new API key on the dashboard.

Changelog

1.1.0 - Addeed secondaryLoginId parameter to connection API

1.0.1 - Documentation updated

1.0.0 - SDK updated to version 2.0

0.9.0beta - Initial release

Getting started

Install the SDK using:

npm i -s basiq-sdk-nodejs

Import the package:

const BasiqSDK = require("basiq-sdk-nodejs");

Common usage examples

Fetching a list of institutions

const BasiqSDK = require("basiq-sdk-nodejs");
 
(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");
 
        const institutions = await session.getInstitutions();
})();

You can specify the version of API when instantiating Session object. When the version is not specified, default version is 1.0.

const BasiqSDK = require("basiq-sdk-nodejs");
 
(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY", "2.0");
 
        const institutions = await session.getInstitutions();
})();

Creating a new connection

const BasiqSDK = require("basiq-sdk-nodejs");
 
(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");
 
        const user = session.forUser(userId)
 
        const job = await user.createConnection(institutionId, loginId, password[, securityCode, secondaryLoginId]);
 
        const connection = await job.waitForCredentials(1000, 60);
})();

Fetching and iterating through transactions

const BasiqSDK = require("basiq-sdk-nodejs"),
    FilterBuilder = BasiqSDK.FilterBuilder;
 
(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");
 
        const user = session.forUser(userId);
 
        try {
                const fb = new FilterBuilder();
                fb.eq("connection.id", connId);
                const transactions = await user.getTransactions(fb);
 
                while (await transactions.next()) {
                        console.log("Number of records: ", transactions.data.length);
                }
        } catch (e) {
                console.error(typeof e, e);
        }
})();

API

The API of the SDK is manipulated using Services and Entities. Different services return different entities, but the mapping is not one to one. All http functions return promises. In case of a failed http resolution the promise rejection will return an error object.

Errors

If an action encounters an error, you will receive an APIError instance. The object contains all available data which you can use to act accordingly.

APIError properties
Error.statusCode
Error.response
Error.message

Check the docs for more information about relevant fields in the error object.

Filtering

Some of the methods support adding filters to them. The filters are created using the FilterBuilder function. After instantiating the object, you can invoke methods in the form of comparison(field, value).

Example:

const fb = new FilterBuilder();
fb.eq("connection.id", "conn-id-213-id").gt("transaction.date", "2018-01-01");
const transactions = user.getTransactions(fb)

This example filter for transactions will match all transactions for the connection with the id of "conn-id-213-id" and that are newer than "2018-01-01". All you have to do is pass the filter to the method when you want to use it.

Services

Session

Creating a new Session object

(possible API versions: "1.0" and "2.0", default version: "1.0")

const session = await BasiqSDK.Session("YOUR_API_KEY");
const session = await BasiqSDK.Session("YOUR_API_KEY", "API_VERSION");

UserService

The following are APIs available for the User service

Creating a new UserService
const userService = BasiqSDK.User(session);
Referencing a user

Note: The following action will not send an HTTP request, and can be used to perform additional actions for the instantiated user.

const user = userService.for(userId);
Creating a new User
const user = await userService.new({
        email: "",
        mobile: ""
})
Getting a User
const user = await userService.get(userId);
Update a User
const user = await userService.update(user, {
    email: "",
    mobile: ""
});
Delete a User
const result = await userService.delete(user);
Refresh connections
const result = await userService.refreshAllConnections(user);
List all connections
const conns = await userService.getAllConnections(userId, filter);
Get account
const acc = await userService.getAccount(userId, accountId);
Get accounts
const accs = await userService.getAccounts(userId, filter);
Get transaction
const transaction = await userService.getTransaction(userId, transactionId)
Get transactions
const transactions = await userService.getTransactions(userId, filter)

ConnectionService

The following are APIs available for the Connection service

Creating a new ConnectionService
const connService = new BasiqSDK.Connection(session, user);
Get connection
const connection = await connService.get(connectionId)
Get connection entity with ID without performing an http request
const connection = connService.for(connection)
Create a new connection
const job = await connService.new(institutionId, loginId, password[, securityCode, secondaryLoginId])
Update connection
const job = await connService.update(connection, password[, securityCode, secondaryLoginId]);
Delete connection
const result = await connService.delete(connection);

JobService

The following are APIs available for the Job service

Creating a new JobService
jobService = new BasiqSDK.Job(session, connectionService)
Get a job
const job = await jobService.get(jobId);
Get a job entity with ID without performing an http request
const job = jobService.for(jobId);
Get the related connection for the job
const connection = await jobService.getConnection(job);
Wait for the credential step to be resolved

(interval is in milliseconds, timeout is in seconds)

const connection = await jobService.waitForCredentials(job, interval, timeout);
Entities
Updating a user instance
const user = await user.Update({
        email: "",
        mobile: ""
});
Deleting a user
const result = await user.delete();
Get all of the user's accounts
const accounts = await user.getAccounts();
Get a user's single account
const account = await user.getAccount(accountId);
Get all of the user's transactions
transactions = await user.getTransactions();
Get a user's single transaction
transaction = await user.getTransaction(transactionId);
Create a new connection
job = await user.createConnection();
Refresh all connections
result = await user.refreshAllConnections();

Connection

Refresh a connection
job = await connection.refresh();
Update a connection
job = await connection.update(password[, securityCode, secondaryLoginId]);
Delete a connection
err = await connection.delete();

Job

Get the connection id (if available)
connectionId = job.getConnectionId();
Get the connection
connection = await job.getConnection();
Get the connection after waiting for credentials step resolution

(interval is in milliseconds, timeout is in seconds)

connection = await job.waitForCredentials(interval, timeout);
Get the connection after waiting for transactions step resolution

(interval is in milliseconds, timeout is in seconds)

connection = await job.waitForTransactions(interval, timeout);

Transaction list

Getting the next set of transactions [mut]
await transactions.next();

Dependencies (2)

Dev Dependencies (5)

Package Sidebar

Install

npm i basiq-sdk-nodejs

Weekly Downloads

83

Version

1.1.3

License

MIT

Unpacked Size

57.5 kB

Total Files

5

Last publish

Collaborators

  • aleksandar-basiq
  • lnenad