finicity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 64b9a11eb9733de5c18f224d22ffc52cf2053921
+  data.tar.gz: 7c92ae39b471529d735eadf2acaab8b0f2b8d17a
+SHA512:
+  metadata.gz: f01c8b5be48f0b3413126a3e4c8003e3d78dcb8c4652080ec3ffceb259f03f91e462f77e4cc99f79052dea9f8b6bae2f8c8bd3c177107691fde0abf3482eeddb
+  data.tar.gz: 358e584e41e566ca2877473391dc9f0a9874d3d8999ff3a44a5f3498aa9ef681ef72d6d99e6832e235fafc08c6abf27780d7507e5d00db82eac9b50edfe0c07a

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.ruby-*
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in finicity.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Brian Stien
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+finicity
+========
+
+A gem to communicate easily with Finicity's API
+
+Installation
+============
+
+gem install finicity
+
+or
+
+add ```gem 'finicity'``` to your project's Gemfile
+
+Configuration
+=============
+
+You can configure the finicity gem with the following initializer
+
+```Ruby
+Finicity::V1.configure do |config|
+  config.base_url = "https://finicity.com"
+  config.partner_key = "key"
+  config.username = "moneydesktop"
+  config.password = "password"
+end
+```
+
+or within a Rails project
+
+add a file named ```config/finicity.yml```
+
+with the keys of the same name, and this will be loaded automatically via railtie
+
+Usage
+=====
+
+In order to connect with Finicity you must first create a session. This is
+done by a partner_authentication POST request, and if successful the response
+will contain a token that is valid for a limited time.
+
+Creating a session can be done by making a new client and then authenticating
+
+```Ruby
+client = Finicity::V1::Client.new
+client.authenticate!
+```
+
+If you have an existing session, you can re-open your existing session
+
+```Ruby
+client = Finicity::V1::Client.new("token-123")
+```
+
+If you have an existing session, and also need to re-open a mfa session,
+you can pass both tokens into the client when you create it
+
+```Ruby
+client = Finicity::V1::Client.new("token-123", "mfa_session-123")
+```
+
+Once you have established a session, you can begin to issue commands to the API
+using your finicity client
+
+```Ruby
+client.get_institutions_by_name("Chase")
+```
+
+TODO: link to docs to list all API commands we support

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'special_delivery/gem_tasks'
+require "rspec/core/rake_task"
+
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run specs (default)"
+task :default => :spec

data/finicity.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'finicity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "finicity"
+  spec.version       = Finicity::VERSION
+  spec.authors       = ["Moneydesktop"]
+  spec.email         = ["dev@moneydesktop.com"]
+  spec.summary       = %q{A gem to communicate easily with Finicity's API}
+  spec.description   = %q{A gem to communicate easily with Finicity's API}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'httpclient', '>= 2.4.0'
+  spec.add_dependency 'nokogiri', '>= 1.6.0' # needed so that sax-machine knows which xml parser to use
+  spec.add_dependency 'saxomattic', '>= 0.0.3'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '>= 3.1.0'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'special_delivery'
+end

data/lib/finicity.rb

@@ -0,0 +1,42 @@
+require 'httpclient'
+require 'httpclient/include_client'
+require 'logger'
+require 'saxomattic'
+require 'uri'
+
+require 'finicity/version'
+
+require 'finicity/client'
+require 'finicity/configuration'
+require 'finicity/errors'
+require 'finicity/logger'
+
+require 'finicity/v1'
+require 'finicity/v2'
+
+module Finicity
+  ##
+  # Class methods
+  #
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @config ||= ::Finicity::Configuration.new
+  end
+
+  def self.logger
+    configuration.logger
+  end
+
+  # Class aliases
+  class << self
+    alias_method :config, :configuration
+  end
+
+  # Initialize the config object
+  config
+end
+
+require "finicity/railtie" if defined?(Rails)

data/lib/finicity/client.rb

@@ -0,0 +1,350 @@
+module Finicity
+  class Client
+    ##
+    # Attributes
+    #
+    attr_accessor :mfa_session, :token
+
+    ##
+    # Constructor
+    #
+    def initialize(token = nil, mfa_session = nil)
+      @token = token
+      @mfa_session = mfa_session
+    end
+
+    ##
+    # Instance Methods
+    #
+    # The accounts parameter is an array of Finicity::V1::Reponse::Account
+    def activate_accounts(customer_id, institution_id, accounts)
+      request = ::Finicity::V1::Request::ActivateAccounts.new(token, customer_id, institution_id, accounts)
+      request.log_request
+      response = request.activate_accounts
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    # The accounts parameter is an array of Finicity::V1::Reponse::Account
+    # The mfa_credentials parameter is an array of hashes with keys :text, :answer
+    def activate_accounts_with_mfa(customer_id, institution_id, accounts, mfa_credentials)
+      request = ::Finicity::V1::Request::ActivateAccountsWithMfa.new(token, mfa_session, customer_id, institution_id, accounts, mfa_credentials)
+      request.log_request
+      response = request.activate_accounts_with_mfa
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def add_customer(user_guid)
+      request = ::Finicity::V1::Request::AddCustomer.new(token, user_guid)
+      request.log_request
+      response = request.add_customer
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Customer.parse(response.body)
+        return parsed_response
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def authenticate!
+      request = ::Finicity::V2::Request::PartnerAuthentication.new
+      response = request.authenticate
+
+      if response.ok?
+        parsed_response = ::Finicity::V2::Response::PartnerAuthentication.parse(response.body)
+        @token = parsed_response.token
+        parsed_response
+      else
+        fail ::Finicity::AuthenticationError.new(response.body, response.status_code)
+      end
+    end
+
+    def delete_customer(customer_id)
+      request = ::Finicity::V1::Request::DeleteCustomer.new(token, customer_id)
+      response = request.delete_customer
+
+      if response.ok?
+        # No data to parse, so return a hash for consistent return type
+        return {}
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    # The login_credentials parameter is an array of hashes with the keys :id, :name, :value
+    def discover_accounts(customer_id, institution_id, login_credentials)
+      request = ::Finicity::V1::Request::DiscoverAccounts.new(token, customer_id, institution_id, login_credentials)
+      request.log_request
+      response = request.discover_accounts
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    # The login_credentials parameter is an array of hashes with the keys :id, :name, :value
+    # The mfa_credentials parameter is an array of hashes with keys :text, :answer
+    def discover_accounts_with_mfa(customer_id, institution_id, login_credentials, mfa_credentials)
+      request = ::Finicity::V1::Request::DiscoverAccountsWithMfa.new(token, mfa_session, customer_id, institution_id, login_credentials, mfa_credentials)
+      request.log_request
+      response = request.discover_accounts_with_mfa
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_accounts(customer_id, institution_id)
+      request = ::Finicity::V1::Request::GetAccounts.new(token, customer_id, institution_id)
+      request.log_request
+      response = request.get_accounts
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_customer_by_username(username)
+      request = ::Finicity::V1::Request::GetCustomersByUsername.new(token, username, 1, 1)
+      request.log_request
+      response = request.get_customers_by_username
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Customers.parse(response.body)
+        if parsed_response.found && parsed_response.found > 1
+          raise ::Finicity::DuplicateCustomerError.new(username)
+        else
+          return parsed_response.customers.first
+        end
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_customers_by_username(username, start, limit)
+      request = ::Finicity::V1::Request::GetCustomersByUsername.new(token, username, start, limit)
+      request.log_request
+      response = request.get_customers_by_username
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Customers.parse(response.body)
+        return parsed_response.customers
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_customers
+      request = ::Finicity::V1::Request::GetCustomers.new(token)
+      start = 1
+      limit = 25
+      customers = []
+
+      loop do
+        response = request.get_customers(start, limit)
+
+        if response.ok?
+          parsed_response = ::Finicity::V1::Response::Customers.parse(response.body)
+          customers << parsed_response.customers
+
+          if parsed_response.more_available?
+            start += limit
+          else
+            return customers.flatten
+          end
+        else
+          raise_generic_error!(response)
+        end
+      end
+    end
+
+    def get_institution(institution_id)
+      request = ::Finicity::V1::Request::GetInstitution.new(token, institution_id)
+      response = request.get_institution
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Institution.parse(response.body)
+        return parsed_response
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_institutions(institution_name)
+      request = ::Finicity::V1::Request::GetInstitutions.new(token, institution_name)
+      start = 1
+      limit = 25
+      institutions = []
+
+      loop do
+        response = request.get_institutions(start, limit)
+
+        if response.ok?
+          parsed_response = ::Finicity::V1::Response::Institutions.parse(response.body)
+          institutions << parsed_response.institutions
+
+          if parsed_response.more_available?
+            start += limit
+          else
+            return institutions.flatten
+          end
+        else
+          raise_generic_error!(response)
+        end
+      end
+    end
+
+    def get_login_form(institution_id)
+      request = ::Finicity::V1::Request::GetLoginForm.new(token, institution_id)
+      response = request.get_login_form
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::LoginForm.parse(response.body)
+        return parsed_response.login_fields
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def get_transactions(customer_id, account_id, from_date, to_date)
+      request = ::Finicity::V1::Request::GetTransactions.new(token, customer_id, account_id, from_date, to_date)
+      request.log_request
+      response = request.get_transactions
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Transactions.parse(response.body)
+        return parsed_response.transactions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def interactive_refresh_account(customer_id, account_id)
+      request = ::Finicity::V1::Request::InteractiveRefreshAccount.new(token, customer_id, account_id)
+      request.log_request
+      response = request.interactive_refresh_account
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    # The mfa_credentials parameter is an array of hashes with keys :text, :answer
+    def interactive_refresh_account_with_mfa(customer_id, account_id, mfa_credentials)
+      request = ::Finicity::V1::Request::InteractiveRefreshAccountWithMfa.new(token, mfa_session, customer_id, account_id, mfa_credentials)
+      request.log_request
+      response = request.interactive_refresh_account_with_mfa
+      log_response(response)
+
+      if response.status_code == 200
+        @mfa_session = nil
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      elsif response.status_code == 203
+        @mfa_session = response.headers["MFA-Session"]
+        parsed_response = ::Finicity::V1::Response::Mfa.parse(response.body)
+        return parsed_response.questions
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    def refresh_accounts(customer_id)
+      request = ::Finicity::V1::Request::RefreshAccounts.new(token, customer_id)
+      request.log_request
+      response = request.refresh_accounts
+      log_response(response)
+
+      if response.ok?
+        parsed_response = ::Finicity::V1::Response::Accounts.parse(response.body)
+        return parsed_response.accounts
+      else
+        raise_generic_error!(response)
+      end
+    end
+
+    private
+
+    def log_response(response)
+      ::Finicity.logger.debug do
+        log = "RESPONSE"
+        log << "\n  STATUS CODE: #{response.status_code}"
+        log << "\n  BODY: #{response.body}"
+        log
+      end
+    end
+
+    def raise_generic_error!(response)
+      if response.content_type =~ /application\/xml/i
+        error = ::Finicity::V1::Response::Error.parse(response.body)
+        error_message = error.message
+        error_code = error.code
+      else
+        error_message = response.body
+        error_code = nil
+      end
+
+      fail ::Finicity::GenericError.new(error_message, response.status_code, error_code)
+    end
+
+  end
+end