node package manager

pepper-mint

pepper-mint

An unofficial, promise-based mint.com API in node.js. Builds on the work by mroony

Usage

NPM

require('pepper-mint')(user, pass, cookie)
.then(function(mint) {
    console.log("Logged in...");
 
    // return another promise
    // (or you can then() it here, of course,
    //  if you need more API calls)
    return mint.getAccounts();
})
.then(function(accounts) {
 
    // accounts is the array of account objects
    accounts.forEach(function(account) {
        // EG: "Bank of America", "Savings", 1234567
        console.log(account.fiName, account.accountName, account.accountId);
    });
})
.catch(function(err) {
    console.error("Boo :(", err);
});

Mint Cookie

Because of an update to the authorization flow of Mint.com, the API now requires a couple cookies, which are passed to the pepper-mint library as a string. These are called ius_session and thx_guid.

To get the value of these cookies, you can use Chrome and login to Mint.com, then open the Developer Tools and check the Application tab. On the left should be an item called Cookies, which you can expand to see https://mint.intuit.com and https://pf.intuit.com, at least. ius_session can be found on the former, and thx_guid can be found on the latter.

You can pass these separately as:

require('pepper-mint')(username, password, ius_session, thx_guid)

or as a cookie-style string (for backwards compatibility):

require('pepper-mint')(username, password,
    `ius_session=${ius_session};thx_guid=${thx_guid}`)

Furthermore, if you don't want to extract them by hand at all, pepper-mint includes a mechanism to drive a Chrome browser and extract it automatically---just be aware that using this method will probably require you to input a two-factor auth code. If you want to persist the cookies fetched by this method, they will be stored as .sessionCookies on the Mint instance:

require('pepper-mint')(username, password)
.then(function(mint) {
    // NOTE: this is spelled out to clarify the format
    // of the sessionCookies property
    persistCookies({
        ius_session: mint.sessionCookies.ius_session,
        thx_guid: mint.sessionCookies.thx_guid,
    });
});

API

Everything returns a promise for convenient chaining (and also because I wanted to try it out).

require('pepper-mint')

Returns a Login function, which accepts a mint.com username and password as its arguments, and returns a Promise which, when resolved, passes a PepperMint API object. All methods below are called on that object, and return a Promise. In this context, "returns" is a shorthand to mean "the promise resolves with."

mint.getAccounts()

Returns an array of Accounts.

mint.getCategories()

Returns a list of Categories (for categorizing transactions)

mint.getTags()

Returns a list of user-defined Tags

mint.getTransactions([args])

Returns a list of Transactions, optionally filtered by account and/or offset. args is an optional dictionary, with keys accountId and offset, both optional.

mint.createTransaction(args)

Create a new cash transaction.

NB: There is currently very little arg validation, and the server seems to silently reject issues, too :(

Args should look like:

{
   accountId: 1234 // apparently ignored, but good to have, I guess?
   amount: 4.2
   category: {
       id: id
     , name: name
   }
   date: "MM/DD/YYYY"
   isExpense: bool
   isInvestment: bool
   merchant: "Merchant Name"
   note: "Note, if any"
   tags: [1234, 5678] // set of ids
}

category is Optional; if not provided, will just show up as UNCATEGORIZED, it seems

mint.deleteTransaction(transactionId)

Delete a transaction by its ID