Algoan NestJS Budget Insight connector

A simple connector using NestJS framework to connect your service to Budget Insight.

Table of contents

• About Algoan and Budget Insight
• Goal and Philosophy
• Listened Subscriptions
  • Bankreader Link Required
  • Bankreader configuration required
  • Bankreader required
• Application Structure
• Usage
  • Requirements
  • Installation
  • Running the app
  • Test
  • How to test locally
  • How to configure
  • Using Docker
• Contributing
  • Instructions
  • Code Style
• Support

About Algoan and Budget Insight

• Algoan helps companies to build the best open banking experience for credits. To see our products, please refer to our official website
• Budget Insight is a French banking data aggregator for financial services.

Goal and Philosophy

A connector is a web software able to connect a provider to Algoan's API. It subscribes to REST Hooks which lets Algoan notifying the connector when an specific event happens.

More information on the official documentation.

The nestjs-budget-insight-connector focuses on a user bank accounts and transactions. The main goal of this connector is to be able to retrieve a user bank data when Algoan wishes to.

Listened Subscriptions

This section describes the process required for each subscriptions for a Bank reader connector.

Bankreader Link Required

When the Budget Insight user interface is not hosted by Algoan, the user needs to be redirected to an external page. The diagram below describes interactions:

Refers to the bankreader_link_required event.

Bankreader configuration required

If the user interface is hosted by Algoan, the connector needs to set the plug-in for the frontend application:

Refers to the bankreader_configuration_required event.

Bankreader required

When the user has finished the aggregation process, the connector has to retrieve user's banks accounts and transactions. The behavior is slightly different is you use the bankreader_link_required or the bankreader_configuration_required event.

Refers to the bankreader_required event.

Redirection to BI user interface

Using Algoan's BI plug-in

Application Structure

• config/: stores all configurations for the application. It uses node-config-ts to generate a type definition of the default.json file.
• src/algoan/: Algoan module getting your service accounts. It uses the @algoan/rest library.
• src/hooks/: Entry point for your RestHook called by Algoan. It handles events you've subscribed to.
• src/aggregator: contains all API calls to Budget Insight. It also handles the mapping between Budget Insight and Algoan.
• test/: contains e2e tests.

Usage

How to use locally this connector.

Requirements

This connector is a Node.js application available on Docker Hub. Before reading further, you need to download and install Node.js.

Installation

Clone the repository:

$ git clone https://github.com/algoan/nestjs-budget-insight-connector.git --depth=1

Install all dependencies running:

$ npm install

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

How to test locally

To test locally the Budget Insight process, a simple index.html file is rendered. To use it:

• Create a config/user/{process.env.USER}.json file to override app configurations. NOTE: This application uses node-config-ts. See the How to configure section for further information.
• Run npm start
• Go to your favorite browser and navigate to http://localhost:8080. It should display a web page:

• Click on the first button "Launch BI redirection process". It will create a new Banks User and triggers the hooks controller.
• To be redirected to Budget Insight, click on the second button "Redirect to BI" . This will get your banks-user and redirect you to the Budget Insight redirect URL. If an alert appears, it means that the Banks user has not been updated.

How to configure

To configure your application properly, here is a list of key to set:

Property name	Mandatory	Type	Description
algoan	Yes	object	Algoan base configurations to retrieve service accounts
algoan.baseUrl	Yes	string	Algoan host URL
algoan.clientId	Yes	string	OAuth2 Client ID provided by Algoan
algoan.clientSecret	Yes	string	OAuth2 Client Secret provided by Algoan
budgetInsight	No	object	Budget Insight credentials if it is not set in your service account
budgetInsight.url	No	string	Budget Insight sandbox URL
budgetInsight.clientId	No	string	Budget Insight Client ID for the sandbox
budgetInsight.clientSecret	No	string	Budget Insight Client secret for the sandbox
budgetInsight.synchronizationTimeout	No	number	Timeout in seconds after each the synchronization trial is cancelled
budgetInsight.waitingTime	No	number	Time in seconds to wait between each call to get items
targetUrl	No	string	Target URL for your resthook. See the documentation for more information
eventList	No	array	Event List you want to subscribe to
restHooksSecret	No	string	Resthooks secrets ensuring that all calls are made by Algoan. See the documentation for more information
port	No	number	Application networking port

NOTE: Default values are defined in the config/default.json file.

Using Docker

If you use a Docker environment, you can pull the latest version of the connector on Algoan's docker hub registry.

$ docker pull algoan/nestjs-budget-insight-connector

Then run the application:

$ docker run -p 8080:8080 algoan/nestjs-budget-insight-connector

As the docker image uses a production NODE_ENV and the node-config-ts library, you need to create a config/deployment/production.secret.json file with your configurations or use environment variables:

Variable	Description
ALGOAN_BASE_URL	Algoan host to retrieve service accounts
ALGOAN_CLIENT_ID	Client ID used to connect to Algoan
ALGOAN_CLIENT_SECRET	Client Secret used to connect to Algoan

Example:

$ docker run -p 8080:8080 -e ALGOAN_BASE_URL=https://api.preprod.algoan.com \ 
  -e ALGOAN_CLIENT_ID=test \
  -e ALGOAN_CLIENT_SECRET=password \
  algoan/nestjs-budget-insight-connector

NOTE: For security reasons, the index.html is not served in production environment.

Contributing

We would love to have your contribute, thank you for that! 🎉

If you want to add missing APIs, or correct an issue, you will have to follow this list of instructions.

Instructions

• Set up your local environment by forking the repository.
• When you are about to commit, commitlint is running to check if your commit message respects conventional commit.
• Write tests, there is a high coverage on the repository. Simply run npm run test:cov to generate a coverage/ directory.
• Respect coding style. Run npm run lint to check if there are errors.
• Open a Pull Request where you describe the feature/issue you are about to publish.

Code Style

This project uses ESLint to analyze the TypeScript code. Commit are linted too thanks to commitlint and the conventional commit format.

Support

If you need credentials for your service, please contact [email protected].