Creating extensions

You can create extensions to cater for your specific needs easily. Extensions can be written in any language but we will use Javascript here as there are readily available helper packages to make extension creation easier. Here, we will create a simple text-based transaction import extension as an example here but the concepts can be adapted universally.

Starting point

Here's a boilerplate to get you started:

require('@prudent/text-import').start(function(content) {

    console.log(content);
    
});

From a dependency point of view, that's all you need to know! The content variable contains the content that you can parse. This is in the form of raw text for CSV based files.

The @prudent/text-import package embeds the communication protocol from the Prudent core process to the extension. All you need to do now is parse content to create an array of transaction objects that can then be sent back to the Prudent core process.

For a list of helper packages that are available for different file formats, see Extension creation helpers.

Setting up the project

Before we look at parsing contents, let's take some time to setup the project.

Let's create an extension that can deal with QIF (Quicken Interchange Format). We shall save the code thus far as qif.js in a directory called qif.

As we may want to eventually publish this extension as an npm package (and also because we want to keep track of dependencies), within the qif directory:

$ npm init --y

Let's pull in a couple of dependencies:

$ npm install --save @prudent/text-import qif2json

We will use qif2json to help with parsing the QIF content.

Parsing content into transaction objects

A typical bank data format that in qif looks like this:

!Type:Bank
D12/25/2019
T-50.0
PPrecision Plumbing
LHome Maintenance
^
D12/26/2019
T0.02
PINTEREST
^

Save the above in a file called data.qif or download the samples here.

Let's now add the parsing code to qif.js:

const qif2json = require('qif2json');

require('@prudent/text-import').start(function(content) {
    let parsedContent = qif2json.parse(content, {
        dateFormat: 'us'
    });
});

For the purpose of developing an extension, you can actually do the following to pass the content in data.qif content to your code within the function that's passed to start():

$ node qif.js data.qif
{ transactions: 
   [ { date: '2019-25-12',
       amount: -50,
       payee: 'Precision Plumbing',
       category: 'Home Maintenance' },
     { date: '2019-26-12', amount: 0.02, payee: 'INTEREST' } ],
  type: 'Bank' }

It is possible to call your extension this way as @prudent/text-import has a helper that deals with reading the file, making it a 'mock' content for your function. This makes the development and testing of extensions easier.

Transaction objects

Next, we will need to iterate the transactions array in the parsedContent to turn each transaction into a Prudent-compatible object.

const qif2json = require('qif2json');
const encode  = require('@prudent/encode');

require('@prudent/text-import').start(function(content) {

    let parsedContent = qif2json.parse(content, {
        dateFormat: 'us'
    });

    let transactions = [];

    parsedContent.transactions.forEach(function(item) {

        let transactionObject = encode.transaction(
            encode.dateString(item.date),
            item.payee,
            item.amount,
            item.category
        );

        transactions.push(transactionObject);
        
    });

    console.log(encode.protocol('transactions', transactions));

});

We use encode.dateString() as a convenient helper to make sure item.date is in a format that works best with Prudent. We also use encode.transaction() to create a transaction object that Prudent understands. Lastly, we use encode.protocol() to encode the transactions array in an agreed communication protocol with Prudent before sending it out to stdout with console.log() (using console.log() here as it is common, you can uses console.info() too).

Stdin and stdout is the primary way in which an extension can communicate with Prudent.

Wrapping up

With the above, the extension is ready! Test it with:

$ node qif.js data.qif 
{"name":"transactions","content":[{"date":"2019/12/25","payee":"Precision Plumbing","value":-50,"description":"Home Maintenance"},{"date":"2019/12/26","payee":"Bonus Interest","value":0.02}]}

See the next section on how to make this extension available to Prudent locally (and Sharing extensions section after on how to share it with others!).