charging-client 0.0.2

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/gem_tasks"
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.title = 'charging-client-ruby'
+  rdoc.main = "README.rdoc"
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.include("README.rdoc","lib/**/*.rb")
+  # rdoc.generator = 'darkfish'
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/charging-client.gemspec

@@ -0,0 +1,40 @@
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+# Ensure we require the local version and not one we might have installed already
+require File.join([File.dirname(__FILE__),'lib','charging','version.rb'])
+
+Gem::Specification.new do |spec|
+  spec.name          = "charging-client"
+  spec.version       = Charging::VERSION
+  spec.authors       = ["Rodrigo Tassinari de Oliveira", "Celestino Gomes"]
+  spec.email         = ["rodrigo@pittlandia.net", "rodrigo.tassinari@myfreecomm.com.br", "tinorj@gmail.com", "celestino.gomes@myfreecomm.com.br"]
+  spec.description   = %q{A Ruby client for the Charging REST API}
+  spec.summary       = %q{A Ruby client for the Charging REST API}
+  spec.homepage      = "https://github.com/myfreecomm/charging-client-ruby"
+  spec.license       = "Apache-v2"
+  spec.has_rdoc      = true
+
+  # VCR cassettes are too long for the gemspec, see http://stackoverflow.com/questions/14371686/building-rails-3-engine-throwing-gempackagetoolongfilename-error
+  # spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files`.split($/).reject { |f| f =~ %r{(vcr_cassettes)/} }
+  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.7"
+  spec.add_dependency "multi_json", "~> 1.11"
+
+  spec.add_development_dependency "bundler", "> 1.3.2"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'rdoc', '~> 4.0'
+  spec.add_development_dependency "rspec", "~> 2.13"
+  spec.add_development_dependency "vcr", "~> 2.4"
+  spec.add_development_dependency "webmock", "~> 1.9.3"
+  spec.add_development_dependency "pry", "~> 0.9"
+  spec.add_development_dependency "pry-nav", "~> 0.2"
+  spec.add_development_dependency "awesome_print", "~> 1.1"
+  spec.add_development_dependency "simplecov", "~> 0.7"
+  spec.add_development_dependency "coveralls", "~> 0.6"
+end

data/lib/charging.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+# http://www.ruby-doc.org/stdlib-2.0.0/libdoc/English/rdoc/English.html
+require 'English'
+
+require 'rest_client'
+require 'multi_json'
+
+require 'charging/version'
+require 'charging/helpers'
+require 'charging/configuration'
+require 'charging/http'
+
+require 'charging/collection'
+require 'charging/base'
+require 'charging/service_account'
+require 'charging/domain'
+require 'charging/charge_account'
+require 'charging/invoice'
+
+module Charging
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration) if block_given?
+  end
+  
+  def self.use_sandbox!(application_token = 'AwdhihciTgORGUjnkuk1vg==')
+    Charging.configure do |config|
+      config.url = 'https://sandbox.charging.financeconnect.com.br'
+      config.application_token = application_token
+    end    
+  end
+end

data/lib/charging/base.rb

@@ -0,0 +1,109 @@
+# encoding: UTF-8
+
+module Charging
+  class Base
+    DEFAULT_PAGE = 1
+    DEFAULT_LIMIT = 10
+
+    COMMON_ATTRIBUTES = [:uuid, :uri, :etag]
+    
+    attr_reader :last_response, :errors
+    attr_reader(*COMMON_ATTRIBUTES)
+
+    def initialize(attributes, response)
+      Helpers.load_variables(self, get_attributes, attributes)
+      
+      @last_response = response
+      @errors = []
+      @deleted = false
+      
+      normalize_etag!
+    end
+    
+    def create!(&block)
+      execute_and_capture_raises_at_errors(201) do
+        @last_response = block.call
+      end
+      
+      self
+    end
+    
+    def destroy!(&block)
+      execute_and_capture_raises_at_errors(204) do
+        @last_response = block.call
+      end
+      
+      if errors.empty?
+        @deleted = true
+        @persisted = false
+      end
+      
+      self
+    end
+    
+    def normalize_etag!
+      if @etag.nil?
+        @etag = last_response.headers[:etag] if last_response && last_response.code === 200
+      else
+        @etag = @etag.inspect
+      end
+    end
+    
+    # Returns true if the object exists on Charging service.
+    def persisted?
+      (uuid && etag && uri && !deleted?) || false
+    end
+    
+    # Returns true if the object exists on Charging service.
+    def unpersisted?
+      !persisted?
+    end
+
+    # Returns true if object already deleted on API
+    def deleted?
+      @deleted || false
+    end
+
+    # Returns a hash with attributes
+    def attributes
+      Helpers.hashify(self, self.class::ATTRIBUTES)
+    end
+    
+    def self.validate_attributes!(attributes) # :nodoc:
+      keys = attributes.keys.map(&:to_sym)
+      diff = keys - (const_get(:ATTRIBUTES) + const_get(:READ_ONLY_ATTRIBUTES) + COMMON_ATTRIBUTES)
+      raise ArgumentError, "Invalid attributes for #{self.name}: #{attributes.inspect}" if diff.any?
+    end
+    
+    private
+    
+    def self.raise_last_response_unless(status_code, response)
+      raise Http::LastResponseError.new(response) if response.code != status_code
+    end
+    
+    def raise_last_response_unless(status_code)
+      self.class.raise_last_response_unless(status_code, last_response)
+    end
+    
+    def execute_and_capture_raises_at_errors(success_code, &block)
+      reset_errors!
+      
+      block.call
+
+      raise_last_response_unless success_code
+    ensure
+      if $ERROR_INFO
+        @last_response = $ERROR_INFO.last_response if $ERROR_INFO.kind_of?(Http::LastResponseError)
+        @errors = [$ERROR_INFO.message]
+      end
+    end
+    
+    def reset_errors!
+      @errors = []
+    end
+
+    def get_attributes
+      ((self.class::ATTRIBUTES || []) + (self.class::READ_ONLY_ATTRIBUTES || []) + COMMON_ATTRIBUTES).flatten.uniq
+    end
+  end
+end

data/lib/charging/charge_account.rb

@@ -0,0 +1,169 @@
+# encoding: UTF-8
+
+module Charging
+  class ChargeAccount < Base
+    DEFAULT_PAGE = 1
+    DEFAULT_LIMIT = 10
+
+    READ_ONLY_ATTRIBUTES = [:national_identifier]
+    
+    ATTRIBUTES = [
+      :account, :agency, :name, :portfolio_code, :address, :zipcode, 
+      :sequence_numbers, :currency, :agreement_code, :supplier_name, 
+      :advance_days, :bank, :our_number_range, :default_charging_features,
+      :city_state
+    ]
+
+    attr_accessor(*ATTRIBUTES)
+    attr_reader(*READ_ONLY_ATTRIBUTES, :domain)
+    
+    def initialize(attributes, domain, response = nil)
+      super(attributes, response)
+      @domain = domain
+    end
+
+    # Creates current charge account at API.
+    #
+    # API method: <tt>POST /account/domains/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#post-account-domains
+    def create!
+      super do
+        raise 'can not create without a domain' if invalid_domain?
+
+        ChargeAccount.post_charge_accounts(domain, attributes)
+      end
+
+      reload_attributes!
+    end
+
+    # Deletes the charge account at API
+    # 
+    # API method: <tt>DELETE /charge-accounts/:uuid/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/charges.html#delete-charge-accounts-uuid
+    def destroy!
+      super do
+        Http.delete("/charge-accounts/#{uuid}/", domain.token, etag)
+      end
+    end
+    
+    # Update an attribute on charge account at API.
+    # 
+    # API method: <tt>PATCH /charge-accounts/:uuid/</tt>
+    # 
+    # API documentation: https://charging.financeconnect.com.br/static/docs/charges.html#patch-charge-accounts-uuid
+    def update_attribute!(attribute, value, should_reload_attributes = true)
+      execute_and_capture_raises_at_errors(204) do
+        @last_response = Http.patch("/charge-accounts/#{uuid}/", domain.token, etag, attribute => value)
+      end
+      
+      reload_attributes! if should_reload_attributes
+    end
+    
+    # Update all attributes at charge_account. This method uses
+    # <tt>update_attribute!</tt> recurring for each attrubute.
+    # <tt>attrubutes_valies</tt> should be a hash with attribute and value to
+    # be updated.
+    def update_attributes!(attributes_values)
+      attributes_values.each do |attribute, value|
+        update_attribute! attribute, value, false
+      end
+    ensure
+      reload_attributes!
+    end
+    
+    # Finds a charge account by uuid. It requites an <tt>domain</tt> and a
+    # <tt>uuid</tt>.
+    #
+    # Returns a ChargeAccount instance or raises a Http::LastResponseError if something
+    # went wrong, like unauthorized request, not found.
+    #
+    # API method: <tt>GET /charge-accounts/:uuid/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/charges.html#get-charge-accounts-uuid
+    def self.find_by_uuid(domain, uuid)
+      Helpers.required_arguments!(domain: domain, uuid: uuid)
+      
+      response = ChargeAccount.get_charge_account(domain, uuid)
+      
+      raise_last_response_unless 200, response
+      
+      load_persisted_charge_account(MultiJson.decode(response.body), response, domain)
+    end
+    
+    # Finds all charge accounts for a domain. It requites an <tt>domain</tt>,
+    # and you should pass <tt>page</tt> and/or <tt>limit</tt> to apply on find.
+    #
+    # Returns a Collection (Array-like) of ChargeAccount
+    #
+    # API method: <tt>GET /charge-accounts/?page=:page&limit=:limit</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/charges.html#get-charge-accounts-limit-limit-page-page
+    def self.find_all(domain, page = DEFAULT_PAGE, limit = DEFAULT_LIMIT)
+      Helpers.required_arguments!(domain: domain)
+
+      response = get_charge_accounts(domain, page, limit)
+
+      Collection.new(domain, response)
+    end
+    
+    # Finds a charge account by uri. It requites an <tt>domain</tt> and a
+    # <tt>String</tt>.
+    #
+    # Returns a ChargeAccount instance or raises a Http::LastResponseError if something
+    # went wrong, like unauthorized request, not found.
+    def self.find_by_uri(domain, uri)
+      Helpers.required_arguments!(domain: domain, uri: uri)
+      
+      response = Http.get(uri, domain.token)
+      
+      raise_last_response_unless 200, response
+      
+      ChargeAccount.load_persisted_charge_account(MultiJson.decode(response.body), response, domain)
+    end
+    
+    def self.load_persisted_charge_account(attributes, response, domain)
+      validate_attributes!(attributes)
+      ChargeAccount.new(attributes, domain, response)
+    end
+    
+    private
+    
+    def invalid_domain?
+      domain.nil?
+    end
+    
+    def reload_attributes!
+      new_charge_account = self.class.find_by_uuid(domain, Helpers.extract_uuid(last_response.headers[:location]) || uuid)
+      
+      (ATTRIBUTES + COMMON_ATTRIBUTES + READ_ONLY_ATTRIBUTES).each do |attribute|
+        instance_variable_set "@#{attribute}", new_charge_account.send(attribute)
+      end
+
+      self
+    end
+    
+    def self.get_charge_accounts(domain, page, limit)
+      Http.get("/charge-accounts/?page=#{page}&limit=#{limit}", domain.token)
+    end
+    
+    def self.get_charge_account(domain, uuid)
+      Http.get("/charge-accounts/#{uuid}/", domain.token)
+    end
+    
+    def self.post_charge_accounts(domain, attributes)
+      Http.post('/charge-accounts/', domain.token, MultiJson.encode(attributes))
+    end
+    
+    class Collection < Charging::Collection
+      def initialize(domain, response)
+        super(response, domain: domain)
+      end
+      
+      def load_object_with(attributes)
+        ChargeAccount.load_persisted_charge_account(attributes, last_response, @domain)
+      end
+    end
+  end
+end

data/lib/charging/collection.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Charging
+  # Represents a object collection result. It is a delegator for an array of object.
+  class Collection < SimpleDelegator
+
+    # Responds the last http response from the API.
+    attr_reader :last_response
+
+    def initialize(response, attributes) # :nodoc:
+      Helpers.required_arguments!(attributes.merge('response' => response))
+
+      @last_response = response
+      
+      attributes.each do |attribute, value|
+        instance_variable_set("@#{attribute}", value)
+      end
+      
+      super(load_data_with_response!)
+    end
+
+    def load_data_with_response! # :nodoc:
+      return [] if last_response.code != 200
+
+      raw_lines = MultiJson.decode(last_response.body)
+      raw_lines.map { |raw_line| load_object_with(raw_line) }
+    end
+  end
+end

data/lib/charging/configuration.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+require 'base64'
+
+module Charging
+  class Configuration
+    attr_accessor :application_token, :url, :user_agent
+
+    def initialize(application_token = nil)
+      @application_token = application_token
+      @url = 'https://charging.financeconnect.com.br'
+      @user_agent = "Charging Ruby Client v#{Charging::VERSION}"
+    end
+
+    def credentials_for(token = application_token)
+      check_valid_token!(token)
+      encrypted_token = ::Base64.strict_encode64(":#{token}")
+      "Basic #{encrypted_token}"
+    end
+
+    private
+
+    def check_valid_token!(token = application_token)
+      invalid = token.nil? || token.to_s.strip.empty?
+      raise(ArgumentError, "#{token.inspect} is not a valid token") if invalid
+      true
+    end
+  end
+end

data/lib/charging/domain.rb

@@ -0,0 +1,164 @@
+# encoding: utf-8
+
+module Charging
+  # Represents a Charging domain.
+  class Domain < Base
+    READ_ONLY_ATTRIBUTES = [:token]
+
+    ATTRIBUTES = [ :supplier_name, :address, :city_state, :zipcode, :national_identifier, :description ]
+
+    attr_accessor(*ATTRIBUTES)
+    attr_reader(*READ_ONLY_ATTRIBUTES, :account)
+
+    # Initializes a domain instance
+    def initialize(attributes, account, response = nil)
+      super(attributes, response)
+      @account = account
+    end
+
+    # Creates current domain at API.
+    #
+    # API method: <tt>POST /account/domains/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#post-account-domains
+    def create!
+      super do
+        raise 'can not create without a service account' if invalid_account?
+
+        Domain.post_account_domains(account.application_token, attributes)
+      end
+
+      reload_attributes!
+    end
+
+    # Destroys current domain at API.
+    #
+    # API method: <tt>DELETE /account/domains/:uuid/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#delete-account-domains-uuid
+    def destroy!
+      super do
+        raise 'can not destroy without a service account' if invalid_account?
+        raise 'can not destroy a not persisted domain' unless persisted?
+        
+        Domain.delete_account_domains(self)
+      end
+    end
+
+    # Finds all domains for a specified account. It requites an ServiceAccount
+    # instance, and you should pass <tt>page</tt> and/or <tt>limit</tt> to
+    # apply on find.
+    #
+    # Returns a Collection (Array-like) of Domain
+    #
+    # API method: <tt>GET /account/domains/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#get-account-domains-limit-limit-page-page
+    def self.find_all(account, page = DEFAULT_PAGE, limit = DEFAULT_LIMIT)
+      Helpers.required_arguments!('service account' => account)
+
+      response = get_account_domains(account, page, limit)
+
+      Collection.new(account, response)
+    end
+
+    # Finds a domain by your uuid. It requites an ServiceAccount instance and a
+    # String <tt>uuid</tt>.
+    #
+    # Returns a Domain instance or raises a Http::LastResponseError if something
+    # went wrong, like unauthorized request, not found.
+    #
+    # API method: <tt>GET /account/domains/:uuid/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#get-account-domains-uuid
+    def self.find_by_uuid(account, uuid)
+      Helpers.required_arguments!('service account' => account, uuid: uuid)
+
+      response = get_account_domain(account, uuid)
+
+      raise_last_response_unless 200, response
+
+      load_persisted_domain(MultiJson.decode(response.body), response, account)
+    end
+
+    # Finds a domain by its authentication token. It requites an <tt>token</tt>.
+    #
+    # Returns a Domain instance or raises a Http::LastResponseError if something
+    # went wrong, like unauthorized request, not found.
+    #
+    # API method: <tt>GET /domain/</tt>
+    #
+    # API documentation: https://charging.financeconnect.com.br/static/docs/accounts_and_domains.html#get-subuser-domain
+    def self.find_by_token(token)
+      Helpers.required_arguments!('token' => token)
+
+      response = get_domain(token)
+
+      raise_last_response_unless 200, response
+
+      load_persisted_domain(MultiJson.decode(response.body), response)
+    end
+
+    def self.load_persisted_domain(attributes, response, account = nil) # :nodoc:
+      validate_attributes!(attributes)
+      Domain.new(attributes, account, response)
+    end
+
+    private
+
+    def reload_attributes!
+      new_domain = self.class.find_by_uuid(account, Helpers.extract_uuid(last_response.headers[:location]) || uuid)
+
+      (COMMON_ATTRIBUTES + READ_ONLY_ATTRIBUTES).each do |attribute|
+        instance_variable_set "@#{attribute}", new_domain.send(attribute)
+      end
+
+      self
+    end
+
+    def load_errors(*error_messages)
+      @errors = error_messages.flatten
+    end
+
+    def invalid_account?
+      account.nil?
+    end
+
+    def self.delete_account_domains(domain)
+      token = domain.account.application_token
+      Http.delete("/account/domains/#{domain.uuid}/", token, domain.etag)
+    end
+
+    def self.post_account_domains(token, attributes)
+      Http.post('/account/domains/', token, MultiJson.encode(attributes))
+    end
+
+    def self.get_domain(token) # :nodoc:
+      Http.get('/domain/', token)
+    end
+
+    def self.get_account_domain(account, uuid) # :nodoc:
+      Http.get("/account/domains/#{uuid}/", account.application_token)
+    end
+
+    def self.get_account_domains(account, page, limit) # :nodoc:
+      Http.get("/account/domains/?page=#{page}&limit=#{limit}", account.application_token)
+    end
+
+    def self.create_domain_collection_for(response) # :nodoc:
+      data = response.code === 200 ? MultiJson.decode(response.body) : []
+
+      Collection.new(data, response)
+    end
+    
+    class Collection < Charging::Collection
+      def initialize(account, response)
+        super(response, account: account)
+      end
+      
+      def load_object_with(attributes)
+        Domain.load_persisted_domain(attributes, last_response, @account)
+      end
+    end
+  end
+end