bill_forward 1.2014.296

data/bill_forward.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bill_forward/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bill_forward"
+  spec.version       = BillForward::VERSION
+  spec.authors       = ["BillForward"]
+  spec.email         = ["support@billforward.net"]
+  spec.summary       = "BillForward Ruby Client Library"
+  spec.description   = "Enables you to call the BillForward API easily using Ruby"
+  spec.homepage      = "http://www.billforward.net"
+  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 'rest-client', '~> 1.6.8'
+  spec.add_dependency 'json', '~> 1.8.1'
+  spec.add_dependency 'require_all'
+  spec.add_dependency 'activesupport', '>= 3.1.0', '< 4'
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rake"
+end

data/bill_forward.iml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="CompassSettings">
+    <option name="compassSupportEnabled" value="true" />
+  </component>
+  <component name="FacetManager">
+    <facet type="gem" name="Ruby Gem">
+      <configuration>
+        <option name="GEM_APP_ROOT_PATH" value="$MODULE_DIR$" />
+        <option name="GEM_APP_TEST_PATH" value="$MODULE_DIR$/test" />
+        <option name="GEM_APP_LIB_PATH" value="$MODULE_DIR$/lib" />
+      </configuration>
+    </facet>
+  </component>
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="jdk" jdkName="ruby-2.0.0-p451" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v1.6.3, ruby-2.0.0-p451) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json (v1.8.1, ruby-2.0.0-p451) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="mime-types (v2.3, ruby-2.0.0-p451) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rest-client (v1.6.7, ruby-2.0.0-p451) [gem]" level="application" />
+  </component>
+</module>
+

data/lib/bill_forward.rb

@@ -0,0 +1,18 @@
+require 'rest-client'
+require 'json'
+# used for escaping query parameters
+require 'erb'
+
+# Rails extensions
+# 'indifferent hashes' are used to enable string access to entities unserialized with symbol keys
+require 'active_support/core_ext/hash/indifferent_access'
+# we need ordered hashes because API requires '@type' to be first key in object
+require 'active_support/ordered_hash'
+# provides 'blank?' function
+require 'active_support/core_ext/string'
+
+# requirer that negotiates dependency order, relative pathing
+require 'require_all'
+
+# require all ruby files in relative directory 'bill_forward' and all its subdirectories
+require_rel 'bill_forward'

data/lib/bill_forward/billing_entity.rb

@@ -0,0 +1,263 @@
+module BillForward
+	class BillingEntity
+		# legacy Ruby gives us this 'id' chuff. we kinda need it back.
+		undef id if defined? id
+		attr_accessor :_client
+
+		def initialize(state_params = nil, client = nil)
+			raise AbstractInstantiateError.new('This abstract class cannot be instantiated!') if self.class == MutableEntity
+			
+			client = self.class.singleton_client if client.nil?
+			state_params = {} if state_params.nil?
+
+			TypeCheck.verifyObj(Client, client, 'client')
+			TypeCheck.verifyObj(Hash, state_params, 'state_params')
+
+			@_registered_entities = Hash.new
+			@_registered_entity_arrays = Hash.new
+
+			@_client = client
+			# initiate with empty state params
+			# use indifferent hash so 'id' and :id are the same
+			@_state_params = HashWithIndifferentAccess.new
+			# legacy Ruby gives us this 'id' chuff. we kinda need it back.	
+			@_state_params.instance_eval { undef id if defined? id }
+			# populate state params now
+			unserialize_all state_params
+		end
+
+		class << self
+			attr_accessor :resource_path
+
+			def get_by_id(id, query_params = {}, customClient = nil)
+				client = customClient
+				client = singleton_client if client.nil?
+
+				raise ArgumentError.new("id cannot be nil") if id.nil?
+				TypeCheck.verifyObj(Hash, query_params, 'query_params')
+
+				route = resource_path.path
+				endpoint = ''
+				url_full = "#{route}/#{endpoint}#{id}"
+
+				response = client.get_first(url_full, query_params)
+
+				# maybe use build_entity here for consistency
+				self.new(response, client)
+			end
+
+			def get_all(query_params = {}, customClient = nil)
+				client = customClient
+				client = singleton_client if client.nil?
+				
+				TypeCheck.verifyObj(Hash, query_params, 'query_params')
+
+				route = resource_path.path
+				endpoint = ''
+				url_full = "#{route}/#{endpoint}"
+
+				response = client.get(url_full, query_params)
+				results = response["results"]
+
+				# maybe use build_entity_array here for consistency
+				entity_array = Array.new
+				# maybe it's an empty array, but that's okay too.
+				results.each do |value|
+					entity = self.new(value, client)
+					entity_array.push(entity)
+				end
+				entity_array
+			end
+
+			def singleton_client
+				Client.default_client
+			end
+		end
+
+		def method_missing(method_id, *arguments, &block)
+			# no call to super; our criteria is all keys.
+			#setter
+			if /^(\w+)=$/ =~ method_id.to_s
+				return set_state_param($1, arguments.first)
+			end
+			#getter
+			get_state_param(method_id.to_s)
+		end
+
+		def [](key)
+			method_missing(key)
+		end
+
+		def []=(key, value)
+			set_key = key.to_s+'='
+			method_missing(set_key, value)
+		end
+
+		def to_ordered_hash
+			ordered_hash = hash_with_type_at_top(@_state_params)
+			ordered_hash
+		end
+
+		def to_json(*a)
+			ordered_hash = to_ordered_hash
+			ordered_hash.to_json
+			# @_state_params.to_json
+		end
+
+		def to_unordered_hash
+			json_string = to_json
+			JSON.parse(json_string)
+		end
+
+		def to_s
+			parsed = to_unordered_hash
+			JSON.pretty_generate(parsed)
+		end
+
+		def serialize
+			to_json
+		end
+
+	protected
+		def hash_with_type_at_top(hash)
+			new_hash = OrderedHashWithDotAccess.new
+
+			# API presently requires '@type' (if present) to be first key in JSON
+			if hash.has_key? '@type'
+				# insert existing @type as first element in ordered hash
+				new_hash['@type'] = hash.with_indifferent_access['@type']
+			end
+
+			# add key-value pairs excepting '@type' back in
+			# no, we don't care about the order of these.
+			hash.with_indifferent_access.reject {|key, value| key == '@type'}.each do |key, value|
+				new_hash[key] = value
+			end
+
+			return new_hash
+		end
+
+		def set_state_param(key, value)
+			@_state_params[key] = value
+			get_state_param(key)
+		end
+
+		def get_state_param(key)
+			@_state_params[key]
+		end
+
+		def unserialize_all(hash)
+			TypeCheck.verifyObj(Hash, hash, 'hash')
+
+			hash.each do |key, value|
+				unserialized = unserialize_one value
+				set_state_param(key, unserialized)
+			end
+		end
+
+		def unserialize_hash(hash)
+			TypeCheck.verifyObj(Hash, hash, 'hash')
+
+			# API presently requires '@type' (if present) to be first key in JSON
+			hash = hash_with_type_at_top(hash)
+
+			hash.each do |key, value|
+				# recurse down, so that all nested hashes get same treatment
+				unserialized = unserialize_one value
+
+				# replace with unserialized version
+				hash[key] = unserialized
+			end
+
+			hash
+		end
+
+		def unserialize_array(array)
+			TypeCheck.verifyObj(Array, array, 'array')
+
+			array.each_with_index do |value, index|
+				# recurse down, so that all nested hashes get same treatment
+				unserialized = unserialize_one value
+
+				# replace with unserialized version
+				array[index] = unserialized
+			end
+
+			array
+		end
+
+		def unserialize_one(value)
+			if value.is_a? Hash
+				value = unserialize_hash(value)
+			elsif value.is_a? Array
+				value = unserialize_array(value)
+			end
+			value
+		end
+
+		def unserialize_entity(key, entity_class, hash)
+			# ensure that the provided entity class derives from BillingEntity
+			TypeCheck.verifyClass(BillingEntity, entity_class, 'entity_class')
+			TypeCheck.verifyObj(Hash, hash, 'hash')
+
+			# register the entity as one that requires bespoke serialization
+			@_registered_entities[key] = entity_class
+			# if key exists in the provided hash, add it to current entity's model
+			if hash.has_key? key
+				entity = build_entity(entity_class, hash[key])
+				set_state_param(key, entity)
+			end
+		end
+
+		def unserialize_array_of_entities(key, entity_class, hash)
+			# ensure that the provided entity class derives from BillingEntity
+			TypeCheck.verifyClass(BillingEntity, entity_class, 'entity_class')
+			TypeCheck.verifyObj(Hash, hash, 'hash')
+
+			# register the array of entities as one that requires bespoke serialization
+			@_registered_entity_arrays[key] = entity_class
+			# if key exists in the provided hash, add it to current entity's model
+			if hash.has_key? key
+				entities = build_entity_array(entity_class, hash[key])
+				set_state_param(key, entities)
+			end
+		end
+
+		def build_entity_array(entity_class, entity_hashes)
+			TypeCheck.verifyObj(Array, entity_hashes, 'entity_hashes')
+
+			entity_array = Array.new
+			# maybe it's an empty array, but that's okay too.
+			entity_hashes.each do |value|
+				new_entity = build_entity(entity_class, value)
+				entity_array.push(new_entity)
+			end
+			entity_array
+		end
+
+		def build_entity(entity_class, entity)
+			if entity.is_a? Hash
+				# either we are given a serialized entity
+				# we must unserialize it
+
+				# this entity should the same client as we do
+				client = @_client
+
+				new_entity = entity_class.new(entity, client)
+			elsif entity.is_a? entity_class
+				# or we are given an already-constructed entity
+				# just return it as-is
+
+				# for consistency we might want to set this entity to use the same client as us. Let's not for now.
+				new_entity = entity
+			else
+				expectedClassName = entity_class.name
+				actualClassName = entity.class.name
+				raise TypeError.new("Expected instance of either: 'Hash' or '#{expectedClassName}' at argument 'entity'. "+
+					"Instead received: '#{actualClassName}'")
+			end
+
+			new_entity
+		end
+	end
+end

data/lib/bill_forward/client.rb

@@ -0,0 +1,355 @@
+module BillForward
+  class ClientException < Exception
+    attr_accessor :response
+
+    def initialize(message, response=nil)
+      super(message)
+
+      begin
+        if response.nil?
+          self.response = nil
+        else
+          self.response = JSON.parse response
+        end
+      rescue => e
+        self.response = nil
+      end
+    end
+  end
+
+  class ClientInstantiationException < Exception
+  end
+
+  class ApiError < Exception
+    attr_reader :json
+    attr_reader :raw
+
+    def initialize(json, raw)
+      @json = json
+      @raw = raw
+    end
+  end
+
+  class ApiAuthorizationError < ApiError
+  end
+
+  class ApiTokenException < ClientException
+
+  end
+
+  class Client
+    attr_accessor :host
+    attr_accessor :use_logging
+    attr_accessor :api_token
+
+    # provide access to self statics
+    class << self
+      # default client is a singleton client
+      attr_reader :default_client
+      def default_client=(default_client)
+        if (default_client == nil)
+          # meaningless, but required for resetting this class after a test run
+          @default_client = nil
+          return
+        end
+
+        TypeCheck.verifyObj(Client, default_client, 'default_client')
+        @default_client = default_client
+      end
+      def default_client()
+        raise ClientInstantiationException.new("Failed to get default BillForward API Client; " +
+           "'default_client' is nil. Please set a 'default_client' first.") if
+        @default_client.nil?
+        @default_client
+      end
+    end
+
+
+    # Constructs a client, and sets it to be used as the default client.
+    # @param options={} [Hash] Options with which to construct client
+    # 
+    # @return [Client] The constructed client
+    def self.make_default_client(options)
+      constructedClient = self.new(options)
+      self.default_client = constructedClient
+    end
+
+    def initialize(options={})
+      TypeCheck.verifyObj(Hash, options, 'options')
+      @use_logging = options[:use_logging]
+
+      if options[:host]
+        @host = options[:host]
+      else
+        raise ClientInstantiationException.new "Failed to initialize BillForward API Client\n" +
+                                         "Required parameters: :host, and either [:api_token] or all of [:client_id, :client_secret, :username, :password].\n" +
+                                         "Supplied Parameters: #{options}"
+      end
+
+      if options[:use_proxy]
+        @use_proxy = options[:use_proxy]
+        @proxy_url = options[:proxy_url]
+      end
+
+      if options[:api_token]
+        @api_token = options[:api_token]
+      else
+        @api_token = nil
+        if options[:client_id] and options[:client_secret] and options[:username] and options[:password]
+          @client_id = options[:client_id]
+          @client_secret = options[:client_secret]
+          @username = options[:username]
+          @password = options[:password]
+        else
+          raise ClientException.new "Failed to initialize BillForward API Client\n"+
+                                           "Required parameters: :host and :use_logging, and either [:api_token] or all of [:client_id, :client_secret, :username, :password].\n" +
+                                           "Supplied Parameters: #{options}"
+        end
+
+      end
+
+      @authorization = nil
+    end
+
+
+
+    # def get_results(url)
+    #   response = get(url)
+
+    #   return [] if response.nil? or response["results"].length == 0
+
+    #   response["results"]
+    # end
+
+    def get_first(url, params={})
+      response = get(url, params)
+
+      raise IndexError.new("Cannot get first; request returned empty list of results.") if response.nil? or response["results"].length == 0
+
+      response["results"][0]
+    end
+
+    def retire_first(url, params={})
+      response = retire(url, params)
+
+      raise IndexError.new("Cannot get first; request returned empty list of results.") if response.nil? or response["results"].length == 0
+
+      response["results"][0]
+    end
+
+    def put_first(url, data, params={})
+      response = put(url, data, params)
+
+      raise IndexError.new("Cannot get first; request returned empty list of results.") if response.nil? or response["results"].length == 0
+
+      response["results"][0]
+    end
+
+    def post_first(url, data, params={})
+      response = post(url, data, params)
+
+      raise IndexError.new("Cannot get first; request returned empty list of results.") if response.nil? or response["results"].length == 0
+
+      response["results"][0]
+    end
+
+    def execute_request(method, url, token, payload=nil)
+      # Enable Fiddler:
+      if @use_proxy
+        RestClient.proxy = @proxy_url
+      end
+      
+      # content_type seems to be broken on generic execute.
+      # darn.
+      # RestClient::Request.execute(options)
+      options = {
+        :Authorization => "Bearer #{token}",
+        :accept => 'application/json'
+      }
+      if (method == 'post' || method == 'put')
+        options.update(:content_type => 'application/json'
+        )
+      end
+
+      if (method == 'post')
+        RestClient.post(url, payload, options)
+      elsif (method == 'put')
+        RestClient.put(url, payload, options)
+      elsif (method == 'get')
+        RestClient.get(url, options)
+      elsif (method == 'delete')
+        RestClient.delete(url, options)
+      end
+    end
+
+    def get(url, params={})
+      TypeCheck.verifyObj(Hash, params, 'params')
+      request('get', url, params, nil)
+    end
+
+    def retire(url, params={})
+      TypeCheck.verifyObj(Hash, params, 'params')
+      request('delete', url, params, nil)
+    end
+
+    def post(url, data, params={})
+      TypeCheck.verifyObj(String, data, 'data')
+      TypeCheck.verifyObj(Hash, params, 'params')
+      request('post', url, params, data)
+    end
+
+    def put(url, data, params={})
+      TypeCheck.verifyObj(String, data, 'data')
+      TypeCheck.verifyObj(Hash, params, 'params')
+      request('put', url, params, data)
+    end
+
+    private
+      def uri_encode(params = {})
+        TypeCheck.verifyObj(Hash, params, 'params')
+
+        encoded_params = Array.new
+
+        params.each do |key, value|
+          encoded_key = ERB::Util.url_encode key
+          encoded_value = ERB::Util.url_encode value
+          encoded_params.push("#{encoded_key}=#{encoded_value}")
+        end
+        query = encoded_params.join '&'
+        
+      end
+
+      def request(method, url, params={}, payload=nil)
+        full_url = "#{@host}#{url}"
+
+        # Make params into query parameters
+        full_url += "?#{uri_encode(params)}" if params && params.any?
+        token = get_token
+
+        log "#{method} #{url}"
+        log "token: #{token}"
+
+        begin
+          response = execute_request(method, full_url, token, payload)
+
+          parsed = JSON.parse(response.to_str)
+          pretty = JSON.pretty_generate(parsed)
+          log "response: \n#{pretty}"
+
+          return parsed
+        rescue SocketError => e
+          handle_restclient_error(e)
+        rescue NoMethodError => e
+          # Work around RestClient bug
+          if e.message =~ /\WRequestFailed\W/
+            e = APIConnectionError.new('Unexpected HTTP response code')
+            handle_restclient_error(e)
+          else
+            raise
+          end
+        rescue RestClient::ExceptionWithResponse => e
+          if rcode = e.http_code and rbody = e.http_body
+            handle_api_error(rcode, rbody)
+          else
+            handle_restclient_error(e)
+          end
+        rescue RestClient::Exception, Errno::ECONNREFUSED => e
+          handle_restclient_error(e)
+        end
+      end
+
+      def handle_restclient_error(e)
+        connection_message = "Please check your internet connection and try again. "
+
+        case e
+        when RestClient::RequestTimeout
+          message = "Could not connect to BillForward (#{@host}). #{connection_message}"
+        when RestClient::ServerBrokeConnection
+          message = "The connection to the server (#{@host}) broke before the " \
+            "request completed. #{connection_message}"
+        when SocketError
+          message = "Unexpected error communicating when trying to connect to BillForward. " \
+            "Please confirm that (#{@host}) is a BillForward API URL. "
+        else
+          message = "Unexpected error communicating with BillForward. "
+        end
+
+        raise ClientException.new(message + "\n\n(Network error: #{e.message})")
+      end
+
+      def handle_api_error(rcode, rbody)
+        begin
+          # Example error JSON:
+          # {
+          #    "errorType" : "ValidationError",
+          #    "errorMessage" : "Validation Error - Entity: Subscription Field: type Value: null Message: may not be null\nValidation Error - Entity: Subscription Field: productID Value: null Message: may not be null\nValidation Error - Entity: Subscription Field: name Value: null Message: may not be null\n",
+          #    "errorParameters" : [ "type", "productID", "name" ]
+          # }
+
+          error = JSON.parse(rbody)
+
+          errorType = error['errorType']
+          errorMessage = error['errorMessage']
+          if (error.key? 'errorParameters')
+            errorParameters = error['errorParameters']
+            raise_message = "\n====\n#{rcode} API Error.\nType: #{errorType}\nMessage: #{errorMessage}\nParameters: #{errorParameters}\n====\n"  
+          else
+            if (errorType == 'Oauth')
+              split = errorMessage.split(', ')
+
+              error = split.first.split('=').last
+              description = split.last.split('=').last
+
+              raise_message = "\n====\n#{rcode} Authorization failed.\nType: #{type}\nError: #{error}\nDescription: #{description}\n====\n"
+
+              raise ApiAuthorizationError.new(error, rbody), raise_message
+            else
+              raise_message = "\n====\n#{rcode} API Error.\nType: #{errorType}\nMessage: #{errorMessage}\n====\n"  
+            end
+          end
+          
+          raise ApiError.new(error, rbody), raise_message
+        end
+
+        raise_message = "\n====\n#{rcode} API Error.\n Response body: #{rbody}\n====\n"
+        raise ApiError.new(nil, rbody), raise_message
+      end
+
+      def log(*args)
+        if @use_logging
+          puts *args
+        end
+      end
+
+      def get_token
+        if @api_token
+          @api_token
+        else
+          if @authorization and Time.now < @authorization["expires_at"]
+            return @authorization["access_token"]
+          end
+          begin
+            response = RestClient.get("#{@host}oauth/token", :params => {
+                :username => @username,
+                :password => @password,
+                :client_id => @client_id,
+                :client_secret => @client_secret,
+                :grant_type => "password"
+            }, :accept => :json)
+
+            @authorization = JSON.parse(response.to_str)
+            @authorization["expires_at"] = Time.now + @authorization["expires_in"]
+
+            @authorization["access_token"]
+          rescue => e
+            if e.respond_to? "response"
+              log "BILL FORWARD CLIENT ERROR", e.response
+            else
+              log "BILL FORWARD CLIENT ERROR", e, e.to_json
+            end
+            nil
+          end
+        end
+      end
+  end
+end