mondo-clj

This unofficial clojure lib gives simple hooks for the Mondo API. It's pre-alpha and not all functions are finalized.

Installing

Current semantic version:

To use with Leiningen, add

:dependencies [[mondo-clj "0.1.11"]]

to your project.clj.

You can use it in a source file like this:

(:require [mondo-clj.core :as mondo])

or by REPL:

(require '[mondo-clj.core :as mondo])

Usage

Authentication

The Mondo API implements OAuth 2.0 so the first step is to get a token:

(mondo/get-access-token {:client-id "client-id"
                         :client-secret "client-secret"
                         :username "username"
                         :password "password"})

This should return a map similar to this:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :access-token "access_token"
 :client-id "client_id"
 :expires-in 21600
 :refresh-token "refresh_token"
 :token-type "Bearer"
 :user-id "user_id"}

As you can see I'm adding the :status to the returned map to give a bit of context to any errors.

At any time you can get information about an access token, using:

(mondo/whoami "access-token")

returns:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :authenticated true,
 :client-id "client_id",
 :user-id "user_id"}

Accounts

To get a list of accounts:

(mondo/list-accounts "access-token")

Returns something like:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :accounts [{:id "acc_00009237aqC8c5umZmrRdh"
             :description "Peter Pan's Account"
             :created #inst "2015-12-01T00:00:00.000-00:00"}]}

Balance

Get the balance of a specific account

(mondo/read-balance "access-token" "account-id")

Returns:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :balance 50.0
 :currency "GBP"
 :spend-today 0.0}

NB: The Mondo docs currently say that the balance and spend-today return types are 64bit integers in minor units of the currency. Eg. GBP 5000 is £50.00. This seems counter-intuitive to me so I'll be coercing the balance and spend-today to double type so 50.0 is £50.00.

Transactions

Get details of a single transaction. NB: full merchant details are returned:

(mondo/get-transaction "access-token" "transaction-id")

Returns

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :transaction {:account-balance 130.13
               :amount -5.10
               :created #inst "2015-12-01T00:00:00.000-00:00"
               :currency "GBP"
               :description "THE DE BEAUVOIR DELI C LONDON GBR"
               :id "tx_00008zIcpb1TB4yeIFXMzx"
               :merchant {:address {:address "98 Southgate Road"
                                    :city "London"
                                    :country "GB",
                                    :latitude 51.54151
                                    :longitude -0.08482400000002599
                                    :postcode "N1 3JD"
                                    :region "Greater London"}
                          :created #inst "2015-12-01T00:00:00.000-00:00"
                          :group_id "grp_00008zIcpbBOaAr7TTP3sv"
                          :id "merch_00008zIcpbAKe8shBxXUtl"
                          :logo "https://pbs.twimg.com/profile_images/527043602623389696/68_SgUWJ.jpeg"
                          :emoji "🍞"
                          :name "The De Beauvoir Deli Co."
                          :category "eating_out"}
               :metadata {}
               :notes "Salmon sandwich 🍞"
               :is_load false
               :settled true}}

Or list transactions

(mondo/list-transactions {:access-token "access-token" 
                          :account-id "account-id"})

;or 

(mondo/list-transactions {:access-token "access-token" 
                          :account-id "account-id" 
                          :since #inst "2015-12-01T00:00:00.000-00:00"})

;or 

(mondo/list-transactions {:access-token "access-token" 
                          :account-id "account-id"
                          :before #inst "2015-12-01T00:00:00.000-00:00"})

;or 

(mondo/list-transactions {:access-token "access-token" 
                          :account-id "account-id"
                          :since #inst "2015-12-01T00:00:00.000-00:00" :limit 48})

You can also add meta-data to a transaction

(mondo/annotate-transaction "access-token" "transaction-id" {:foo "bar" :baz "quux"})

Feed

You can inject items into an accounts feed

(mondo/create-feed-item {:access-token "access-token"
                         :account-id "account_id"
                         :type "basic"
                         :params {:title "My custom item"
                                  :image-url "www.example.com/image.png"
                                  :background-color "#FCF1EE"
                                  :body-color "#FCF1EE"
                                  :title-color "#333"
                                  :body "Some body text to display"}
                         :url "http://aan.io"}

Webhooks

Web hooks allow your application to receive real-time, push notification of events in an account.

You can register a webhook:

(mondo/register-webhook "access-token" "account-id" "webhook-url")

List the web hooks registered on an account:

(mondo/list-webhooks "access-token" "account-id")

Or delete a webhook to stop receiving transaction events:

(mondo/delete-webhook "access-token" "webhook-id")

Attachments

The first step when uploading an attachment is to obtain a temporary URL to which the file can be uploaded. The response will include a :file-url which will be the URL of the resulting file, and an :upload-url to which the file should be uploaded to.

(mondo/upload-attachment "access-token" "file-name" "file-type")

Returns:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :file-url "https://s3-eu-west-1.amazonaws.com/mondo-image-uploads/user_00009237hliZellUicKuG1/LcCu4ogv1xW28OCcvOTL-foo.png"
 :upload-url "https://mondo-image-uploads.s3.amazonaws.com/user_00009237hliZellUicKuG1/LcCu4ogv1xW28OCcvOTL-foo.png?AWSAccessKeyId=AKIAIR3IFH6UCTCXB5PQ\u0026Expires=1447353431\u0026Signature=k2QeDCCQQHaZeynzYKckejqXRGU%!D(MISSING)"}

Once you have obtained a URL for an attachment, either by uploading to the :upload-url obtained from the upload-attachment endpoint above or by hosting a remote image, this URL can then be registered against a transaction. Once an attachment is registered against a transaction this will be displayed on the detail page of a transaction within the Mondo app.

(mondo/register-attachment "access-token" "external-id" "file-url" "file-type")

Returns:

{:status {:success? true 
          :error-code 200 
          :error-name "OK" 
          :error-body "All is well."}
 :attachment {:id "attach_00009238aOAIvVqfb9LrZh"
              :user_id "user_00009238aMBIIrS5Rdncq9"
              :external-id "tx_00008zIcpb1TB4yeIFXMzx"
              :file-url "https://s3-eu-west-1.amazonaws.com/mondo-image-uploads/user_00009237hliZellUicKuG1/LcCu4ogv1xW28OCcvOTL-foo.png"
              :file-type "image/png"
              :created #inst "2015-12-01T00:00:00.000-00:00"}}

To remove an attachment, simply deregister this using its id

(mondo/deregister-attachment "access-token" "id")

Questions & Shortcomings?

1. Would be really good to have an API version made available. Adding the request header X-Api-Version to make sure of compatibility going forward.
2. It's unclear at this time whether Pagination allows for before to be either an instant or a transaction-id.

License

Copyright © 2015 Adam Neilson

Distributed under the Eclipse Public License either version 1.0.