Source mondo.js

  1. ;(function () {
  2.   'use strict'
  4.   var request = require('request')
  5.   var _ = require('lodash')
  7.   var version = require('../package.json').version
  8.   var apiValues = require('./api.values.json')
  10.   var apiHost = apiValues.host
  11.   var methodPaths = apiValues.resources
  12.   var dateParams = ['since', 'before']
  13.   var client_id
  14.   var client_secret
  16.   /**
  17.    * @module mondo-bank
  18.    * @description
  19.    * ## Usage
  20.    *
  21.    *     mondo = require('mondo-bank')
  22.    *
  23.    * All methods return a promise but can optionally be called with a callback function as the final argument
  24.    *
  25.    * #### Promise style
  26.    *
  27.    *     methodPromise = mondo[$method]([$params])
  28.    *     methodPromise
  29.    *        .then(function(value){
  30.    *          ...
  31.    *        })
  32.    *        .catch(function(err){
  33.    *          ...
  34.    *        })
  35.    *
  36.    * #### Callback style
  37.    *
  38.    *     mondo[method]([$params], function(err, value){
  39.    *       if (err) {
  40.    *        ...
  41.    *       }
  42.    *       ...
  43.    *     })
  44.    */
  46.   // Helper functions
  48.   // Allow params to be aliased
  49.   function dealiasParams (params, aliases) {
  50.     params = _.extend({}, params)
  51.     Object.keys(aliases).forEach(function (param) {
  52.       var aliased = aliases[param]
  53.       aliased = typeof aliased === 'string' ? [aliased] : aliased
  54.       aliased.forEach(function (alias) {
  55.         if (params[param] === undefined && params[alias] !== undefined) {
  56.           params[param] = params[alias]
  57.         }
  58.         delete params[alias]
  59.       })
  60.     })
  61.     return params
  62.   }
  64.   // Allow params to be passed unbracketed
  65.   function bracketifyParams (obj, param) {
  66.     var bracketedObj = {}
  67.     Object.keys(obj).forEach(function (prop) {
  68.       // what if bracketed prop already exists?
  69.       bracketedObj[param + '[' + prop + ']'] = obj[prop]
  70.     })
  71.     return bracketedObj
  72.   }
  74.   // Adds necessary auth header
  75.   function addAuthorizationHeader (options, access_token) {
  76.     options.headers = options.headers || {}
  77.     options.headers.Authorization = 'Bearer ' + access_token
  78.     return options
  79.   }
  81.   function handleApiResponse (options, resolve, reject) {
  82.     request(options, function (err, res) {
  83.       if (err) {
  84.         reject(err)
  85.       } else {
  86.         var data = res.body
  87.         if (res.statusCode === 200) {
  88.           resolve(data)
  89.         } else {
  90.           reject({
  91.             status: res.statusCode,
  92.             error: data
  93.           })
  94.         }
  95.       }
  96.     })
  97.   }
  99.   // Call the API
  100.   function apiRequest (options, fn) {
  101.     options = _.extend({}, options)
  102.     if (options.form && options.form.client_id && options.form.client_secret) {
  103.       client_id = options.form.client_id
  104.       client_secret = options.form.client_secret
  105.     }
  106.     if (options.qs) {
  107.       dateParams.forEach(function (dParam) {
  108.         if (typeof options.qs[dParam] === 'object') {
  109.           options.qs[dParam] = options.qs[dParam].toISOString()
  110.         }
  111.       })
  112.     }
  113.     options.uri = apiHost + options.uri
  114.     options.json = true
  115.     options.headers = options.headers || {}
  116.     options.headers.client = 'NodeMondo-v' + version
  117.     options.method = options.method || 'GET'
  119.     if (typeof Promise === 'undefined') {
  120.       if (!fn) {
  121.         var noCallbackError = new Error('method.missing.callback')
  122.         throw noCallbackError
  123.       }
  124.       return handleApiResponse(options, function (res) {
  125.         fn(null, res)
  126.       }, fn)
  127.     }
  129.     var reqpromise = new Promise(function (resolve, reject) {
  130.       handleApiResponse(options, resolve, reject)
  131.     })
  133.     if (!fn) {
  134.       return reqpromise
  135.     } else {
  136.       reqpromise.then(function (parsed_body) {
  137.         fn(null, parsed_body)
  138.       })
  139.         .catch(function (err) {
  140.           fn(err)
  141.         })
  142.     }
  143.   }
  145.   // Call the API with authentication
  146.   function apiRequestAuthenticated (options, access_token, fn) {
  147.     options = _.extend({}, options)
  148.     options = addAuthorizationHeader(options, access_token)
  149.     return apiRequest(options, fn)
  150.   }
  152.   // API methods
  154.   /**
  155.    * @method token
  156.    * @static
  157.    * @param {object} credentials Mondo credentials
  158.    * @param {string} credentials.client_id Dev API client id
  159.    * @param {string} credentials.client_secret Dev API client secret
  160.    * @param {string} credentials.username Mondo user’s username
  161.    * @param {string} credentials.password Mondo user’s password
  162.    * @param {function} [fn] Callback function
  163.    * @return {object} Response value
  164.    * @description
  165.    * Acquire an access token
  166.    *
  167.    *     tokenPromise = mondo.token({
  168.    *       client_id: client_id,
  169.    *       client_secret: client_secret,
  170.    *       username: username,
  171.    *       password: password
  172.    *     })
  173.    *
  174.    * @see https://getmondo.co.uk/docs/#acquiring-an-access-token
  175.    */
  176.   function token (credentials, fn) {
  177.     var options = {
  178.       method: 'POST',
  179.       uri: methodPaths.token,
  180.       form: _.extend({
  181.         grant_type: 'password',
  182.         client_id: client_id,
  183.         client_secret: client_secret
  184.       }, credentials)
  185.     }
  186.     return apiRequest(options, fn)
  187.   }
  189.   /**
  190.    * @method tokenInfo
  191.    * @static
  192.    * @param {string} access_token Access token
  193.    * @param {function} [fn] Callback function
  194.    * @return {object} Response value
  195.    * @description
  196.    * Get information about an access token
  197.    *
  198.    *     tokenInfoPromise = mondo.tokenInfo(accessToken)
  199.    *
  200.    * @see https://getmondo.co.uk/docs/#authenticating-requests
  201.    */
  202.   function tokenInfo (access_token, fn) {
  203.     var options = {
  204.       uri: methodPaths.tokenInfo
  205.     }
  206.     return apiRequestAuthenticated(options, access_token, fn)
  207.   }
  209.   /**
  210.    * @method refreshToken
  211.    * @static
  212.    * @param {string} refresh_token Refresh token
  213.    * @param {function} [fn] Callback function
  214.    * @return {object} Response value
  215.    * @description
  216.    * Refresh a proviously acquired token
  217.    *
  218.    *     refreshTokenPromise = mondo.refreshToken(refreshToken)
  219.    *
  220.    * or if the client id and secret have not been previously passed
  221.    *
  222.    *     refreshTokenPromise = mondo.refreshToken({
  223.    *       refreshToken: refreshToken,
  224.    *       client_id: client_id,
  225.    *       client_secret: client_secret
  226.    *     })
  227.    *
  228.    * @see https://getmondo.co.uk/docs/#refreshing-access
  229.    */
  230.   function refreshToken (refresh_token, fn) {
  231.     if (typeof refresh_token === 'string') {
  232.       refresh_token = {
  233.         refresh_token: refresh_token
  234.       }
  235.     }
  236.     var options = {
  237.       method: 'POST',
  238.       uri: methodPaths.refreshToken,
  239.       form: _.extend({
  240.         grant_type: 'refresh_token',
  241.         client_id: client_id,
  242.         client_secret: client_secret
  243.       }, refresh_token)
  244.     }
  245.     return apiRequest(options, fn)
  246.   }
  248.   /**
  249.    * @method accounts
  250.    * @static
  251.    * @param {string} access_token Access token
  252.    * @param {function} [fn] Callback function
  253.    * @return {object} Response value
  254.    * @description
  255.    * Get detailed information about customer’s accounts
  256.    *
  257.    *     accountsPromise = mondo.accounts(accessToken)
  258.    *
  259.    * @see https://getmondo.co.uk/docs/#list-accounts
  260.    */
  261.   function accounts (access_token, fn) {
  262.     var options = {
  263.       uri: methodPaths.accounts
  264.     }
  265.     return apiRequestAuthenticated(options, access_token, fn)
  266.   }
  268.   /**
  269.    * @method balance
  270.    * @static
  271.    * @param {string} account_id Account id
  272.    * @param {string} access_token Access token
  273.    * @param {function} [fn] Callback function
  274.    * @return {object} Response value
  275.    * @description
  276.    * Get balance details for an account
  277.    *
  278.    *     balancePromise = mondo.balance(account_id, access_token)
  279.    *
  280.    * @see https://getmondo.co.uk/docs/#read-balance
  281.    */
  282.   function balance (account_id, access_token, fn) {
  283.     var options = {
  284.       uri: methodPaths.balance,
  285.       qs: {
  286.         account_id: account_id
  287.       }
  288.     }
  289.     return apiRequestAuthenticated(options, access_token, fn)
  290.   }
  292.   /**
  293.    * @method transactions
  294.    * @static
  295.    * @param {object|string} params Query object
  296.    * If passed as a string, used as account_id
  297.    * @param {string} params.account_id Account id
  298.    * @param {date|string} [params.since] Date after which to show results (Date object or ISO string)
  299.    * @param {date|string} [params.before] Date before which to show results (Date object or ISO string)
  300.    * @param {int} [params.limit] Max number of transactions to return (100 max)
  301.    * @param {string} access_token Access token
  302.    * @param {function} [fn] Callback function
  303.    * @return {object} Response value
  304.    * @description
  305.    * List transactions
  306.    *
  307.    *     transactionsPromise = mondo.transactions(account_id, access_token)
  308.    *
  309.    * or to filter the results
  310.    *
  311.    *     transactionsPromise = mondo.transactions({
  312.    *       account_id: account_id,
  313.    *       since: since,
  314.    *       before: before
  315.    *       limit: limit
  316.    *     }, access_token)
  317.    *
  318.    * @see https://getmondo.co.uk/docs/#list-transactions
  319.    */
  320.   function transactions (params, access_token, fn) {
  321.     if (typeof params === 'string') {
  322.       params = {
  323.         account_id: params
  324.       }
  325.     }
  326.     var options = {
  327.       uri: methodPaths.transactions,
  328.       qs: params
  329.     }
  330.     return apiRequestAuthenticated(options, access_token, fn)
  331.   }
  333.   /**
  334.    * @method transaction
  335.    * @static
  336.    * @param {object|String} params Transaction params
  337.    * @param {string} params.transaction_id Transaction ID
  338.    * @param {string} [params.expand] Property to expand (merchant)
  339.    * @param {string} access_token Access token
  340.    * @param {function} [fn] Callback function
  341.    * @return {object} Response value
  342.    * @description
  343.    * Get details about a transaction
  344.    *
  345.    *     transactionPromise = mondo.transaction(transaction_id, access_token)
  346.    *
  347.    * or to see expanded info for the merchant
  348.    *
  349.    *     transactionPromise = mondo.transaction({
  350.    *       transaction_id: transaction_id,
  351.    *       expand: 'merchant'
  352.    *     }, access_token)
  353.    *
  354.    * @see https://getmondo.co.uk/docs/#retrieve-transaction
  355.    */
  356.   function transaction (params, access_token, fn) {
  357.     var transaction_id
  358.     if (typeof params === 'string') {
  359.       transaction_id = params
  360.       params = undefined
  361.     } else {
  362.       transaction_id = params.transaction_id
  363.       delete params.transaction_id
  364.     }
  365.     if (params && params.expand) {
  366.       params['expand[]'] = params.expand
  367.       delete params.expand
  368.     }
  370.     var options = {
  371.       uri: methodPaths.transaction + transaction_id,
  372.       qs: params
  373.     }
  374.     return apiRequestAuthenticated(options, access_token, fn)
  375.   }
  377.   /**
  378.    * @method annotateTransaction
  379.    * @static
  380.    * @param {string|object} transaction_id Transaction ID
  381.    * @param {string} [transaction_id.transaction_id] Transaction ID, if passed as object
  382.    * @param {string} [transaction_id.metadata] Metadata, if passed as nested object
  383.    * @param {object} metadata Annotation metadata object
  384.    * @param {object} annotation Alias for metadata
  385.    * @param {object} annotations Alias for metadata
  386.    * @param {string} access_token Access token
  387.    * @param {function} [fn] Callback function
  388.    * @return {object} Response value
  389.    * @description
  390.    * Annotate a transaction
  391.    *
  392.    *     annotateTransactionPromise = mondo.annotateTransaction(transaction_id, {
  393.    *       foo: 'bar'
  394.    *     }, access_token)
  395.    *
  396.    * or
  397.    *
  398.    *     annotateTransactionPromise = mondo.annotateTransaction({
  399.    *       transaction_id: transaction_id,
  400.    *       foo: 'bar'
  401.    *     }, access_token)
  402.    *
  403.    * or
  404.    *
  405.    *     annotateTransactionPromise = mondo.annotateTransaction({
  406.    *       transaction_id: transaction_id,
  407.    *       metadata: {
  408.    *        foo: 'bar'
  409.    *       }
  410.    *     }, access_token)
  411.    *
  412.    * @see https://getmondo.co.uk/docs/#annotate-transaction
  413.    */
  414.   function annotateTransaction (transaction_id, metadata, access_token, fn) {
  415.     if (typeof transaction_id === 'object') {
  416.       fn = access_token
  417.       access_token = metadata
  418.       metadata = _.extend({}, transaction_id)
  419.       transaction_id = metadata.transaction_id
  420.       delete metadata.transaction_id
  421.       metadata = dealiasParams(metadata, {
  422.         metadata: 'annotation'
  423.       })
  424.       metadata = metadata.metadata || metadata
  425.     }
  426.     metadata = bracketifyParams(metadata, 'metadata')
  427.     var options = {
  428.       method: 'PATCH',
  429.       uri: methodPaths.annotateTransaction + transaction_id,
  430.       form: metadata
  431.     }
  432.     return apiRequestAuthenticated(options, access_token, fn)
  433.   }
  435.   /**
  436.    * @method createFeedItem
  437.    * @static
  438.    * @param {object} params Params object
  439.    * @param {string} params.account_id Account ID
  440.    * @param {object} params.params Feed item params
  441.    * @param {string} params.params.title Title for feed item
  442.    * @param {string} params.params.image_url Icon url to use as icon
  443.    * @param {string} [params.params.body] Body text to display
  444.    * @param {string} [params.params.background_color] Background colour
  445.    * @param {string} [params.params.title_color] Title colour
  446.    * @param {string} [params.params.body_color] Body colour
  447.    * @param {string} params.url Feed item url
  448.    * @param {string} access_token Access token
  449.    * @param {function} [fn] Callback function
  450.    * @return {object} Response value
  451.    * @description
  452.    * Publish a new feed entry
  453.    *
  454.    *     createFeedItemPromise = mondo.createFeedItem({
  455.    *       account_id: accountId,
  456.    *       params: {
  457.    *         title: title,
  458.    *         image_url: image_url
  459.    *       },
  460.    *       url: url
  461.    *     }, access_token)
  462.    *
  463.    * @see https://getmondo.co.uk/docs/#create-feed-item
  464.    */
  465.   function createFeedItem (params, access_token, fn) {
  466.     params = _.extend({}, params)
  467.     params.type = params.type || 'basic'
  468.     var feedParams = bracketifyParams(params.params, 'params')
  469.     delete params.params
  470.     params = _.extend(params, feedParams)
  471.     var options = {
  472.       method: 'POST',
  473.       uri: methodPaths.createFeedItem,
  474.       form: params
  475.     }
  476.     return apiRequestAuthenticated(options, access_token, fn)
  477.   }
  479.   /**
  480.    * @method registerWebhook
  481.    * @static
  482.    * @param {string} account_id Account ID
  483.    * @param {string} url Webhook url
  484.    * @param {string} access_token Access token
  485.    * @param {function} [fn] Callback function
  486.    * @return {object} Response value
  487.    * @description
  488.    * Register a webhook
  489.    *
  490.    *     registerWebhookPromise = mondo.registerWebhook(account_id, url, access_token)
  491.    *
  492.    * See https://getmondo.co.uk/docs/#transaction-created for details of the transaction.created event which is sent to the webhook each time a new transaction is created in a user’s account
  493.    *
  494.    * @see https://getmondo.co.uk/docs/#registering-a-web-hook
  495.    */
  496.   function registerWebhook (account_id, url, access_token, fn) {
  497.     var options = {
  498.       method: 'POST',
  499.       uri: methodPaths.registerWebhook,
  500.       form: {
  501.         account_id: account_id,
  502.         url: url
  503.       }
  504.     }
  505.     return apiRequestAuthenticated(options, access_token, fn)
  506.   }
  508.   /**
  509.    * @method webhooks
  510.    * @static
  511.    * @param {string} account_id Account ID
  512.    * @param {string} access_token Access token
  513.    * @param {function} [fn] Callback function
  514.    * @return {object} Response value
  515.    * @description
  516.    * List webhooks
  517.    *
  518.    *     webhooksPromise = mondo.webhooks(account_id, access_token)
  519.    *
  520.    * @see https://getmondo.co.uk/docs/#list-web-hooks
  521.    */
  522.   function webhooks (account_id, access_token, fn) {
  523.     var options = {
  524.       uri: methodPaths.webhooks,
  525.       qs: {
  526.         account_id: account_id
  527.       }
  528.     }
  529.     return apiRequestAuthenticated(options, access_token, fn)
  530.   }
  532.   /**
  533.    * @method deleteWebhook
  534.    * @static
  535.    * @param {string} webhook_id Webhook ID
  536.    * @param {string} access_token Access token
  537.    * @param {function} [fn] Callback function
  538.    * @return {object} Response value
  539.    * @description
  540.    * Delete webhook
  541.    *
  542.    *     deleteWebhookPromise = mondo.deleteWebhook(webhook_id, access_token)
  543.    *
  544.    * @see https://getmondo.co.uk/docs/#deleting-a-web-hook
  545.    */
  546.   function deleteWebhook (webhook_id, access_token, fn) {
  547.     var options = {
  548.       method: 'DELETE',
  549.       uri: '/webhooks/' + webhook_id
  550.     }
  551.     return apiRequestAuthenticated(options, access_token, fn)
  552.   }
  554.   /**
  555.    * @method registerAttachment
  556.    * @static
  557.    * @param {object} params Params object
  558.    * @param {string} params.external_id Transaction ID
  559.    * @param {string} params.file_type File type
  560.    * @param {string} params.file_url File url
  561.    * @param {string} [params.transaction_id] Alias for external_id
  562.    * @param {string} [params.id] Alias for external_id
  563.    * @param {string} [params.type] Alias for file_type
  564.    * @param {string} [params.url] Alias for file_url
  565.    * @param {string} access_token Access token
  566.    * @param {function} [fn] Callback function
  567.    * @return {object} Response value
  568.    * @description
  569.    * Register attachment
  570.    *
  571.    *     registerAttachmentPromise = mondo.registerAttachment({
  572.    *       external_id: transaction_id,
  573.    *       file_type: file_type,
  574.    *       file_url: file_url
  575.    *     }, access_token)
  576.    *
  577.    * @see https://getmondo.co.uk/docs/#register-attachment
  578.    */
  579.   function registerAttachment (params, access_token, fn) {
  580.     params = dealiasParams(params, {
  581.       external_id: ['transaction_id', 'id'],
  582.       file_type: 'type',
  583.       file_url: 'url'
  584.     })
  585.     var options = {
  586.       method: 'POST',
  587.       uri: methodPaths.registerAttachment,
  588.       form: params
  589.     }
  590.     return apiRequestAuthenticated(options, access_token, fn)
  591.   }
  593.   /**
  594.    * @method uploadAttachment
  595.    * @static
  596.    * @description
  597.    * Request upload attachment url
  598.    *
  599.    *     uploadAttachmentPromise = mondo.uploadAttachment({
  600.    *       file_name: file_name,
  601.    *       file_type: file_type
  602.    *     }, access_token)
  603.    *
  604.    * @see https://getmondo.co.uk/docs/#upload-attachment
  605.    * @param {object} params params object
  606.    * @param {string} params.file_name File name
  607.    * @param {string} params.file_type File type
  608.    * @param {string} [params.file] Alias for file_name
  609.    * @param {string} [params.name] Alias for file_name
  610.    * @param {string} [params.type] Alias for file_type
  611.    * @param {string} access_token Access token
  612.    * @param {function} [fn] Callback function
  613.    * @return {object} Response value
  614.    */
  615.   function uploadAttachment (params, access_token, fn) {
  616.     params = dealiasParams(params, {
  617.       file_name: ['file', 'name'],
  618.       file_type: 'type'
  619.     })
  620.     var options = {
  621.       method: 'POST',
  622.       uri: methodPaths.uploadAttachment,
  623.       form: params
  624.     }
  625.     return apiRequestAuthenticated(options, access_token, fn)
  627.   /*
  628.   // rough on the train pretend code to allow upload and register in one call
  629.   if (params.transaction_id) {
  630.     // resolve apiRequest and attach image to it
  631.     var upload = apiRequest(options)
  632.     if (! fn) {
  633.       upload.then(function(parsed_body) {
  634.         fn(null, parsed_body)
  635.       })
  636.         .catch(function(err) {
  637.           fn(err)
  638.         })
  640.   } else {
  641.     return apiRequest(options, fn)
  642.   }
  644.    */
  645.   }
  647.   /**
  648.    * @method deregisterAttachment
  649.    * @static
  650.    * @param {string} attachment_id Attachment ID
  651.    * @param {string} access_token Access token
  652.    * @param {function} [fn] Callback function
  653.    * @return {object} Response value
  654.    * @description
  655.    * Deregister attachment
  656.    *
  657.    *     deregisterAttachmentPromise = mondo.deregisterAttachment(attachment_id, access_token)
  658.    *
  659.    * @see https://getmondo.co.uk/docs/#deregister-attachment
  660.    */
  661.   function deregisterAttachment (attachment_id, access_token, fn) {
  662.     var options = {
  663.       method: 'POST',
  664.       uri: methodPaths.deregisterAttachment,
  665.       form: {
  666.         id: attachment_id
  667.       }
  668.     }
  669.     return apiRequestAuthenticated(options, access_token, fn)
  670.   }
  672.   module.exports = {
  673.     token: token,
  674.     tokenInfo: tokenInfo,
  675.     refreshToken: refreshToken,
  676.     accounts: accounts,
  677.     balance: balance,
  678.     transactions: transactions,
  679.     transaction: transaction,
  680.     annotateTransaction: annotateTransaction,
  681.     createFeedItem: createFeedItem,
  682.     webhooks: webhooks,
  683.     registerWebhook: registerWebhook,
  684.     deleteWebhook: deleteWebhook,
  685.     uploadAttachment: uploadAttachment,
  686.     registerAttachment: registerAttachment,
  687.     deregisterAttachment: deregisterAttachment
  688.   }
  689. })()