clearbooks 0.16.3

data/lib/clearbooks/interface/thor/mixin/config_choice.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+# @module     module Mixin
+# @brief    Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module   ConfigChoice Module
+  # @brief    Module wrapper around ConfigChoice tasks
+  module ConfigChoice
+
+    def config_choice
+      defaults = YAML.load_file(File.expand_path( File.dirname( __FILE__ ) + '/../../../template/default_values.yml'))
+      defaults['clearbooks'].each_key { |key| choice_option(defaults['clearbooks'], key) }
+      defaults
+    end
+
+    private def choice_option(defaults, option)
+      print ("%s (%s): " % [option, defaults[option]])
+      value = STDIN.gets.chomp
+      defaults[option] = value unless value.empty?
+    end
+  end # of module ConfigChoice
+
+end # of module Mixin
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/mixin/configuration.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+
+# @module       module Mixin
+# @brief        Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module     Configuration Module
+  # @brief      Module wrapper around tasks which demands config file
+  module Configuration
+
+    # @fn       def initialize *args {{{
+    # @brief    Default constructor
+    #
+    # @param    [Array]     args      Argument array
+    def initialize *args
+      super
+      unless File.exist?("~/.clearbooks/config.yaml")
+          abort("Could not find configuration file in ~/clearbooks/config.yaml. Please run 'clearbooks config:generate' to generate it.")
+      end
+    end # }}}
+
+  end # of module Configuration
+
+end # of module Mixin
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/mixin/default.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+
+# System includes
+require 'thor'
+require 'andand'
+
+
+# @module       module Mixin
+# @brief        Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module     Default Module
+  # @brief      Module wrapper around default tasks
+  module Default
+
+    # @fn       def initialize *args {{{
+    # @brief    Default constructor
+    #
+    # @param    [Array]     args      Argument array
+    def initialize *args
+      super
+    end # }}}
+
+  end # of module Default
+
+end # of module Mixin
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/mixin/default_config.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+# Custom includes
+require File.expand_path( File.dirname( __FILE__ ) + '/config_choice' )
+
+# @module       module Mixin
+# @brief        Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module     DefaultConfig Module
+  # @brief      Module wrapper around default tasks
+  module DefaultConfig
+
+    # Include various partials
+    include ::Mixin::ConfigChoice
+
+    def defaults
+      config_path = File.expand_path( '~/.clearbooks/config.yml' )
+      if File.exists?(config_path)
+        YAML.load_file(config_path)
+      else
+        FileUtils.mkdir_p( File.expand_path( '~/.clearbooks' ) )
+        config_choice
+      end
+    end
+  end # of module DefaultConfig
+
+end # of module Mixin
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/mixin/guess.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+
+# System includes
+require 'andand'
+
+
+# @module     module Mixin
+# @brief      Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module   Guess Module
+  # @brief    Module wrapper around guess tasks to extract version numbers etc
+  module Guess
+
+    # @fn       def initialize *args {{{
+    # @brief    Default constructor
+    #
+    # @param    [Array]     args      Argument array
+    def initialize *args
+      super
+    end # }}}
+
+    # @fn       def guess_version string {{{
+    # @brief    Guess version from full version string
+    #
+    # @example  e.g. "ruby 2.1.1p76 (2014-02-24 revision 45161) [i686-linux]"
+    #                   -> 2.1.1
+    #
+    #                "rake, version 10.1.1"
+    #                   -> 10.1.1
+    def guess_version string
+
+      result      = ""
+
+      begin
+
+        # Sanity
+        raise ArgumentError, "Version has to be of type string" unless( string.is_a?( String ) )
+        raise ArgumentError, "Version can't be empty" if( string.empty? )
+
+        result    = string.match( /\d+\.\d+\.\d+/ ).to_s # matches first only
+
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result    = ""
+      end
+
+      return result
+    end # }}}
+
+  end # of Module Guess
+
+end # of module Mixin
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/mixin/shell.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+
+
+# System includes
+require 'andand'
+require 'ptools'
+require 'tempfile'
+
+# Custom includes
+require File.expand_path( File.dirname( __FILE__ ) + '/guess' )
+
+
+# @module     module Mixin
+# @brief      Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module   Shell Module
+  # @brief    Module wrapper around shell commands
+  module Shell
+
+    include ::Mixin::Guess
+
+    # @fn       def initialize *args {{{
+    # @brief    Default constructor
+    #
+    # @param    [Array]     args      Argument array
+    def initialize *args
+      super
+    end # }}}
+
+    ## Actions
+
+    # @fn       def run command {{{
+    # @brief    Run the given command gracefully (without throwing exceptions)
+    #
+    # @param    [String]        command         The command to run
+    # @param    [RegExp]        regexp          Optional regular expression used for matching output
+    #
+    # @return   [String]        Returns empty string if command not found or other problem,
+    #                           otherwise result of command.
+    def run command, regexp = nil
+
+      result      = ''
+
+      begin
+        if( regexp.nil? )
+          result  = execute( command ).strip
+        else
+          raise ArgumentError, 'Regular Expression input needs to be of type Regexp' unless( regexp.is_a?( Regexp ) )
+
+          result  = execute( command ).andand.send( :match, regexp ).andand.send( :to_s ).strip
+        end
+
+      rescue Exception => e
+        say '(EE) ' + e.message, :red
+        result    = ''
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def execute command {{{
+    # @brief    Execute single shell command
+    #
+    # @param    [String]          command         Shell command string with arguments
+    #
+    # @return   [String]          Returns result of command
+    #
+    # @throws   [ArgumentError]   Throws exception if command not found
+    def execute command
+
+      exists  = which( command )
+      raise ArgumentError, "Command not found" unless( exists )
+      result  = `#{command}`
+
+      return result
+    end # }}}
+
+    # @fn       def which command {{{
+    # @brief    Checks if command is available
+    #
+    # @param    [String]        command         Shell command string with or without arguments.
+    #                                           If arguments are given, they are split on first
+    #                                           whitespace and discarded
+    #
+    # @return   [Boolean]       Returns boolean true if command is available, false if not
+    #
+    #
+    # @info     Crude alternative: `#{command} 2>/dev/null`.strip.empty?
+    def which command
+      result      = false
+
+      begin
+        partial   = command.to_s
+        partial   = partial.split(' ').first.to_s if( partial =~ %r{ }i )
+        path      = File.which( partial )
+
+        result    = true unless( path.nil? )
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result    = false
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def version command {{{
+    # @brief    Prints the version of given command, if command exists
+    #
+    # @param    [String]        command         Command string to probe version for, e.g. ruby
+    #
+    # @return   [String]        Returns version string or empty if command not found / error
+    def version command
+
+      result      = ""
+
+      begin
+
+        # Sanity
+        raise ArgumentError, "Command not found" unless( which( command ) )
+
+        # Get usage help screen for command
+        help      = usage( command )
+
+        # Get version flag from help screen
+        flag      = version_flag( help )
+
+        return result if( flag.empty? ) # some stupid commands don't follow standard rules, e.g. bundle
+
+        # Get actual version string
+        banner    = run( command + " " + flag )
+
+        # Guess way to extract and extract semver
+        result    = guess_version( banner.to_s )
+
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result    = ""
+      end
+
+      return result
+    end # }}}
+
+
+    alias_method :exists?, :which
+
+    private
+
+    # @fn       def usage command {{{
+    # @brief    Extracts help/usage screen from command
+    #
+    # @param    [String]        command         Command string
+    #
+    # @return   [String         Result screen output string
+    def usage command
+
+      result        = ""
+
+      begin
+
+        # Some commands misbehave when using wrong arguments
+        # e.g. java
+        help        = []
+
+        # Collect all possible outputs
+        %w(--help -h -help).each do |argument|
+          tempfile  = Tempfile.new( "clearbooks-" )
+          `#{command} #{argument} > #{tempfile.path.to_s} 2>&1`
+          help      <<  File.read( tempfile.path )
+        end
+
+        # Prune to relevent one
+        help.each do |h|
+
+          # Sanity
+          next if( h.strip.empty? )
+          next if( h.split( "\n" ).length < 4 )
+          next unless( h.match( /unknown/i ).to_s.empty? )           # does it contain unknown? (argument)
+          next unless( h.match( /unrecognized/i ).to_s.empty? )      # does it contain unrecognized? (argument)
+          next unless( h.match( /error/i ).to_s.empty? )             # does it contain error
+          next unless( h.match( /does not exist/i ).to_s.empty? )    # does not exist error
+          next unless( result.empty? )
+
+          result    = h
+
+        end # of help.each
+
+
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result      = ""
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def version_flag usage {{{
+    # @brief    Extracts version flag from usage help screen of command
+    #
+    # @param    [String]        usage         Usage help screen output (string), e.g. ruby --help
+    #
+    # @return   [String]        Returns the string which according to help screen will print version
+    #                           e.g. -version for java
+    def version_flag usage
+
+      result        = ""
+
+      begin
+        result      = usage.match( /--version/i ).to_s
+        result      = usage.match( /-version/i ).to_s if( result.empty? )
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result      = ""
+      end
+
+      return result
+    end # }}}
+
+  end # of Module Shell
+
+end # of module Mixin
+
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/interface/thor/version.thor

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+require 'clearbooks/version'
+
+# @class  Server command class
+# @brief  Implements the server command
+class Version < Thor
+
+  default_task :show
+
+  ## API
+
+  # @fn       def show {{{
+  # @brief    Show version string of app
+  desc 'show', 'Show version of this app'
+  def show
+    version = Clearbooks::VERSION
+
+    puts version
+  end # }}}
+
+
+  private
+
+  no_tasks do
+
+    ## Actions
+
+  end # of no_tasks do
+
+end # of Class Version
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/library/client.rb

@@ -0,0 +1,257 @@
+#!/usr/bin/env ruby
+
+# System include
+require 'savon'
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class      Clearbooks SOAP client {{{
+  # @brief      interacts with Clearbooks API via Savon
+  #
+  # @note       You should not use it directly. Use static methods in Clearbooks module instead.
+  # @example    Clearbooks.list_invoices
+  #             Clearbooks.create_entity(Clearbooks::Entity.new(...))
+  #
+  class Client
+
+    extend Savon::Model
+
+    client  wsdl:         Clearbooks.config.wsdl,
+            log:          Clearbooks.config.log,
+            logger:       Clearbooks.config.logger,
+            soap_header:  {  'tns:authenticate' => '', attributes!: {'tns:authenticate' => { apiKey: Clearbooks.config.api_key } } }
+
+    operations :create_invoice, :list_invoices, :create_entity, :list_entities, :delete_entity,
+               :create_project, :list_projects, :list_account_codes, :create_journal, 
+               :delete_journal, :create_payment, :allocate_payment
+
+
+    # @fn       def list_invoices {{{
+    # @brief    Get list of invoices from Clearbooks API
+    #
+    # @param    [Hash]    query     Hash of options to filter invoices. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/listinvoices/
+    #
+    # @return   [Array, Invoice]    An array or invoices.
+    #
+    # @example  Clearbooks.list_invoices
+    #
+    def list_invoices query = {}
+      defaults  = { ledger: :sales }
+      query     = defaults.merge(query)
+      response  = super message: {query: '', attributes!: {query: query}}
+      response  = response.to_hash
+      Invoice.build response[:list_invoices_response][:create_invoices_return][:invoice]
+    end # }}}
+
+    # @fn       def create_invoice {{{
+    # @brief    Creates invoice via Clearbooks API.
+    #
+    # @param    [Invoice]   invoice     An invoice to be created. See the list of available options in official API docs: https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+    #
+    # @return   [Hash]      [:due, :invoice_id, :invoice_prefix, :invoice_number] according to official API docs.
+    #
+    # @example
+    #   Clearbooks.create_invoice Clearbooks::Invoice.new(date_created: Date.today,
+    #     credit_terms: 30,
+    #     entity_id: 1,
+    #     type: 'purchases',
+    #     items: [
+    #         Clearbooks::Item.new(description: 'abcd', unit_price: 10,
+    #                              quantity: 5, type: '1001001', vat: 0, vat_rate: '0.00:Out')
+    #     ])
+    #
+    def create_invoice invoice
+      response = super message: invoice.to_savon
+      response = response.to_hash
+      response = response[:create_invoice_response][:create_invoice_return]
+      {
+          due:            BigDecimal.new(response[:@due]),
+          invoice_id:     response[:@invoice_id].to_i,
+          invoice_prefix: response[:@invoice_prefix],
+          invoice_number: response[:@invoice_number]
+      }
+    end # }}}
+
+    # @fn       def create_entity {{{
+    # @brief    Creates entity via Clearbooks API
+    #
+    # @param    [Entity]    entity      An entity to be created. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+    #
+    # @return   [Hash]      [:entity_id] ID of the created entity.
+    #
+    # @example
+    #  Clearbooks.create_entity Clearbooks::Entity.new(company_name: 'DataLogic',
+    #         contact_name: 'Oleg Kukareka',
+    #             address1: 'Kiev',
+    #             country: 'UA',
+    #             postcode: '04073',
+    #             email: 'info@datalogic.co.uk',
+    #             website: 'https://datalogic.co.uk',
+    #             phone1: '01234 567890',
+    #             supplier: {
+    #             default_account_code: '1001001',
+    #             default_credit_terms: 30,
+    #             default_vat_rate: 0
+    #         })
+    #
+    def create_entity entity
+      response = super message: entity.to_savon
+      response = response.to_hash
+      { entity_id: response[:create_entity_response][:create_entity_return].to_i }
+    end # }}}
+
+    # @fn       def list_entities {{{
+    # @brief  Get list of entities from Clearbooks API.
+    # @param  [Hash] query Hash of options to filter entities. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/list-entities/
+    # @return [Array, Entity] An array or entities.
+    # @example
+    #   Clearbooks.list_entities
+    def list_entities query = {}
+      attributes = {query: query.except(:id)}
+      response = super message: {query: {id: query[:id]}, attributes!: attributes}
+      response = response.to_hash
+      Entity.build response[:list_entities_response][:entities][:entity]
+    end # }}}
+
+    # @fn       def delete_entity {{{
+    # @brief    Deletes entity via Clearbooks API.
+    #
+    # @param    [Fixnum]    entity_id     Id of the entity to be deleted. See official docs: https://www.clearbooks.co.uk/support/api/docs/soap/deleteentity/
+    #
+    # @return   [Boolean]   True if the request was successful, otherwise false.
+    #
+    # @example
+    #  Clearbooks.delete_entity 10
+    #
+    def delete_entity entity_id
+      response = super message: {entityId: entity_id}
+      response = response.to_hash
+      response[:delete_entity_response][:delete_entity_success]
+    end # }}}
+
+    # @fn       def create_project {{{
+    # @brief    Creates project via Clearbooks API.
+    #
+    # @param    [Project]     project     A project to be created. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+    #
+    # @return   [Hash]        [:project_id] ID of the created project.
+    #
+    # @example
+    #       Clearbooks.create_project Project.new(description: 'Project 1 description',
+    #                   project_name: 'Project 1 name',
+    #                   status: 'open')
+    def create_project project
+      response = super message: project.to_savon
+      response = response.to_hash
+      { project_id: response[:create_project_response][:create_project_return][:@project_id].to_i }
+    end # }}}
+
+    # @fn       def list_projects {{{
+    # @brief    Get list of projects from Clearbooks API.
+    #
+    # @param    [Hash]    query     Hash of options to filter projects. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/listprojects/
+    #
+    # @return   [Array, Project] An array or projects.
+    #
+    # @example
+    #   Clearbooks.list_projects
+    def list_projects query = {}
+      response = super message: {query: query}
+      response = response.to_hash
+      Project.build response[:list_projects_response][:projects][:project]
+    end # }}}
+
+    # @fn       def list_account_codes {{{
+    # @brief    Get list of account codes from Clearbooks API.
+    #
+    # @return   [Array, AccountCode] An array or projects.
+    #
+    # @example
+    #   Clearbooks.list_account_codes
+    def list_account_codes
+      response = super
+      response = response.to_hash
+      AccountCode.build response[:list_account_codes_response][:account_codes][:account_code]
+    end # }}}
+
+    # @fn       def create_journal {{{
+    # @brief    Creates journal via Clearbooks API.
+    #
+    # @param    [Journal]     journal     A journal to be created. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+    #
+    # @return   [Hash] [:journal_id] ID of the created journal.
+    #
+    def create_journal journal
+      response = super message: journal.to_savon
+      response = response.to_hash
+      { journal_id: response[:create_journal_response][:create_journal_return][:@journal_id].to_i }
+    end # }}}
+
+    # @fn       def delete_journal {{{
+    # @brief    Deletes journal via Clearbooks API.
+    #
+    # @param    [Fixnum]    journal_id    Id of the journal to be deleted.
+    #
+    # @return   [Boolean]   True if the request was successful, otherwise false.
+    #
+    # @example  Clearbooks.delete_journal 10
+    # @see      https://www.clearbooks.co.uk/support/api/docs/soap/deletejournal/
+    def delete_journal journal_id
+      response = super message: {journalId: journal_id}
+      response = response.to_hash
+      response[:delete_journal_response][:journal_success]
+    end # }}}
+
+    # @fn       def create_payment {{{
+    # @brief    Create payment via Clearbooks API
+    #
+    # @param    [Payment]     payment     The payment to be created. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+    #
+    # @return   [Hash]        [:payment_id] ID of the created payment.
+    # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+    #
+    def create_payment payment
+      response = super message: payment.to_savon
+      response = response.to_hash
+      { payment_id: response[:create_payment_response][:create_payment_return][:@payment_id].to_i }
+    end # }}}
+
+    # @fn       def allocate_payment {{{
+    # @brief    Allocate a payment against an invoice or set of invoices.
+    #
+    # @param    [Hash]      params      Params of the payment. See the list of available options in official docs: https://www.clearbooks.co.uk/support/api/docs/soap/allocatepayment/
+    #
+    # @return   [Hash]      [:success, :msg] Operation results and brief message.
+    # @see      https://www.clearbooks.co.uk/support/api/docs/soap/allocatepayment/
+    def allocate_payment params
+      invoices = params[:invoices].map do |i|
+        {
+            :@id      => i[:id],
+            :@amount  => i[:amount]
+        }
+      end
+
+      payment = {
+          :@paymentId => params[:payment_id],
+          :@entityId  => params[:entity_id],
+          :@type      => params[:type],
+          :invoices   => { invoice: invoices }
+      }
+
+      response = super message: {payment: payment}
+      response = response.to_hash
+      response = response[:allocate_payment_response][:status]
+      {
+          success:  response[:@success].to_b,
+          msg:      response[:@msg]
+      }
+    end # }}}
+
+  end # of class Client
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby