clearbooks 0.16.3

data/lib/clearbooks/library/configuration.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+# System include
+require 'yaml'
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Configuration
+  # @brief    Handles configurations of clearbooks gem such as api keys
+  class Configuration
+
+    attr_accessor :api_key, :wsdl, :log, :logger
+
+    # @fn       def initialize
+    # @brief    Constructor for Clearbooks::Configuration class objects
+    def initialize
+      defaults  = YAML.load_file(DEFAULT_CONFIG) rescue nil
+      defaults  ||= YAML.load_file(File.expand_path("~/#{DEFAULT_CONFIG}")) rescue Hash.new
+
+      @api_key  = ENV['CLEARBOOKS_API_KEY'] || defaults['api_key']
+      @wsdl     = defaults['wsdl'] || 'https://secure.clearbooks.co.uk/api/wsdl/'
+      @logger   = Logger.new(STDOUT) if @log = defaults['log']
+
+      self
+    end # }}}
+
+  end # of module Configuration
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/account_code.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks AccountCode model
+  # @brief    Used to get list of available account codes.
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+  class AccountCode < Base
+
+    attr_reader :id, :account_name, :group_name, :default_vat_rate, :show_sales, :show_purchases
+
+    # @!attribute [r] id
+    # Optional. The internal id of the account code.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @!attribute [r] account_name
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @!attribute [r] group_name
+    # Optional. The name of the group the account code is assigned to.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @!attribute [r] default_vat_rate
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @!attribute [r] show_sales
+    # Optional. Boolean value of whether the account code shows in the sales invoice form.
+    # @return [Boolean]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @!attribute [r] show_purchases
+    # Optional. Boolean value of whether the account code shows in the purchase invoice form.
+    # @return [Boolean]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for AccountCode model
+    #
+    # @param    [Hash]     data      Account code attributes. See https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+    def initialize data
+      @id               = data.savon(:id).to_i
+      @account_name     = data.savon :account_name
+      @group_name       = data.savon :group_name
+
+      @default_vat_rate = data.savon :default_vat_rate
+
+      @show_sales       = data.savon(:show_sales).to_b
+      @show_purchases   = data.savon(:show_purchases).to_b
+    end # }}}
+
+  end # of class AccountCode
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/base.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Base class for Clearbooks API models
+  # @brief    Implements common operations related to Savon and SOAP
+  class Base
+
+    class << self
+
+      # @fn       def build {{{
+      # @brief    Builds an array of items from a hash returned by Savon
+      #
+      # @param    [Array]   data    An array of hashes representing collection or a hash representing a single item
+      #
+      # @return   [Array]   List of items that represent collection from hash returned by Savon
+      #
+      # @note     Still returns an array when called with a hash representing a single item.
+      def build data
+        unless data.is_a? Array
+          [ create(data) ]
+        else
+          return data.map { |d| create(d) }
+        end
+      end  # }}}
+
+      # @fn       def create {{{
+      # @brief    Creates an item from a hash returned by Savon
+      #
+      # @param    [Hash]    data    Hash representing a single object returned by Savon
+      #
+      # @return   [Object]  An item instantiated from a hash returned by Savon
+      def create data
+        if data.is_a? Hash
+          new data
+        else
+          data
+        end
+      end # }}}
+
+    end # of class << self
+
+
+    protected
+
+    # @fn       def parse_date date {{{
+    # @brief    Parses a given date in expected form from upstream API
+    #
+    # @param    [String]      date        Date string to parse
+    #
+    # @return   [Date]        Returns Date or DateTime from string parsing result
+    def parse_date date
+      if date.nil? || date.is_a?(Date)
+        date
+      else
+        DateTime.strptime date, '%Y-%m-%d %H:%M:%S'
+      end
+    end # }}}
+
+  end # of class Base
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/entity.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Entity model
+  # @brief    Used to list existing entities or create new.
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+  class Entity < Base
+
+    attr_reader :id,
+                :company_name,  # string required
+                :contact_name,  # string optional
+                :building,      # string optional
+                :address1,      # string optional
+                :address2,      # string optional
+                :town,          # string optional
+                :county,        # string optional
+                :country,       # string optional
+                # country codes http://www.iso.org/iso/support/country_codes/iso_3166_code_lists/iso-3166-1_decoding_table.htm
+                :postcode,      # string optional
+                :email,         # string optional
+                :phone1,        # string optional
+                :phone2,        # string optional
+                :fax,           # string optional
+                :website,       # string optional
+                :external_id,   # integer optional
+                :statement_url,
+                :supplier,
+                   # default_account_code   string optional
+                   # default_vat_rate       string optional
+                   # default_credit_terms   integer optional
+                :customer
+                   # default_account_code   string optional
+                   # default_vat_rate       string optional
+                   # default_credit_terms   integer optional
+
+    # @!attribute [r] id
+    # @return [Fixnum] Entity Id.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] statement_url
+    # @return [String] The URL the customer/supplier can access to view statements.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] company_name
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] contact_name
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] building
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] address1
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] address2
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] town
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] county
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] country
+    # Optional. Country code.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] postcode
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] email
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] phone1
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] phone2
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] fax
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] website
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] external_id
+    # Optional.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] supplier
+    # Optional. [:default_account_code, :default_vat_rate, :default_credit_terms]
+    # @return [Hash]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+    # @!attribute [r] customer
+    # Optional. [:default_account_code, :default_vat_rate, :default_credit_terms]
+    # @return [Hash]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+
+
+    # @fn         def initialize data {{{
+    # @brief      Constructor of Entity class handling entity ie. personal data
+    #
+    # @param      [Hash]     data        Entity attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
+    #
+    def initialize data
+      @id               = data.savon(:id).to_i
+      @company_name     = data.savon :company_name
+      @contact_name     = data.savon :contact_name
+
+      @building         = data.savon :building
+      @address1         = data.savon :address1
+      @address2         = data.savon :address2
+      @town             = data.savon :town
+      @county           = data.savon :county
+      @country          = data.savon :country
+      @postcode         = data.savon :postcode
+
+      @email            = data.savon :email
+      @phone1           = data.savon :phone1
+      @phone2           = data.savon :phone2
+      @fax              = data.savon :fax
+      @website          = data.savon :website
+
+      @statement_url    = data.savon :statement_url
+      @external_id      = data.savon(:external_id).to_i
+
+      @supplier = entity_extra data.savon :supplier
+      @supplier = @supplier.from_savon if @supplier
+
+      @customer = entity_extra data.savon :customer
+      @customer = @customer.from_savon if @customer
+
+    end # }}}
+
+    # @fn         def to_savon {{{
+    # @brief      Converts given Entity (self) to savon readable format
+    #
+    # @return     [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+        entity: {
+          :@company_name  => @company_name,
+          :@contact_name  => @contact_name,
+
+          :@building      => @building,
+          :@address1      => @address1,
+          :@address2      => @address2,
+          :@town          => @town,
+          :@county        => @county,
+          :@country       => @country,
+          :@postcode      => @postcode,
+
+          :@email         => @email,
+          :@phone1        => @phone1,
+          :@phone2        => @phone2,
+          :@fax           => @fax,
+          :@website       => @website,
+
+          :@external_id   => @external_id,
+          :supplier       => entity_extra(@supplier),
+          :customer       => entity_extra(@customer)
+        }.compact
+      }
+    end # }}}
+
+
+    private
+
+    # @fn         def entity_extra extra {{{
+    # @brief      Convert supplier/customer attributes to Savon readable format.
+    #
+    # @param      [Hash]       extra         Supplier or customer attributes.
+    #
+    # @return     [Hash]       Supplier/customer attributes in Savon readable format
+    def entity_extra extra
+      if extra
+        {
+            :@default_account_code	=> extra[:default_account_code],
+            :@default_vat_rate      => extra[:default_vat_rate],
+            :@default_credit_terms  => extra[:default_credit_terms].to_i,
+        }.compact
+      end
+    end # }}}
+
+
+  end # of class Entity
+
+end # of module Clearbooks
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/invoice.rb

@@ -0,0 +1,163 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Invoice model
+  # @brief    Used to list existing invoices or create new.
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+  class Invoice < Base
+
+    attr_reader :invoice_id, :date_created, :date_due, :date_accrual, :credit_terms, :description, 
+                :entity_id, :reference, :project, :status, :invoice_prefix,
+                :invoice_number, :external_id, :statement_page, :date_modified, :items, :type, :bank_payment_id
+
+    # @!attribute [r] invoice_id
+    # @return [Fixnum] Invoice Id.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] date_created
+    # Required. The tax point of the invoice.
+    # @return [DateTime]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] date_due
+    # Required. The date the invoice is due.
+    # Use either this field or creditTerms.
+    # @return [DateTime]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] date_accrual
+    # Optional. The invoice accrual date.
+    # @return [DateTime]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] credit_terms
+    # Required. The number of days after the tax point that the invoice is due.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] description
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] entity_id
+    # Required. The customer or supplier id.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] reference
+    # Optional. A reference string for the invoice.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] project
+    # Optional. The id of the project to assign the invoice to.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] type
+    # Optional. A string identifying the type of the invoice.
+    # Value one of: purchases, sales, cn-sales, cn-purchases.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] bank_payment_id
+    # Optional. The bank account code.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] date_modified
+    # @return [DateTime] Date this invoice was last modified.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] external_id
+    # @return [Fixnum] Id used to link imported invoices.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] invoice_number
+    # @return [String] Invoice number.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] items
+    # Required.
+    # @return [Item] A list of item elements identifying the line items.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] statement_page
+    # @return [String] A link to a printable invoice page with a link to download as a PDF (top right corner).
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] status
+    # @return [String] Invoice status: paid, unpaid.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] invoice_prefix
+    # @return [String] Invoice prefix.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Invoice model
+    #
+    # @param    [Hash]     data      Invoice attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+    def initialize data
+      @invoice_id       = data.savon(:invoice_id).to_i
+
+      @date_created     = parse_date data.savon(:date_created)
+      @date_due         = parse_date data.savon(:date_due)
+
+      @credit_terms     = data.savon(:credit_terms).to_i
+      @description      = data.savon :description
+
+      @entity_id        = data.savon(:entity_id).to_i
+      @reference        = data.savon :reference
+      @project          = data.savon(:project).to_i
+      @status           = data.savon :status
+
+      @invoice_prefix   = data.savon :invoice_prefix
+      @invoice_number   = data.savon :invoice_number
+      @external_id      = data.savon(:external_id).to_i
+      @statement_page   = data.savon :statement_page
+
+      @date_modified    = parse_date data.savon(:date_modified)
+      @date_accrual     = parse_date data.savon(:date_accrual)
+
+      @type             = data.savon(:type)
+      @bank_payment_id  = data.savon(:bank_payment_id).to_i
+
+      @items = Item.build( data[:items].is_a?(Array) ? data[:items] : data[:items][:item] )
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Invoice (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+        invoice: {
+          :@dateCreated => @date_created,
+          :@entityId    => @entity_id,
+          :@type        => @type,
+          :@dateDue     => @date_due,
+          :@dateAccural => @date_accural,
+          :@creditTerms => @credit_terms,
+          :@reference   => @reference,
+          :@project     => @project,
+
+          description:  @description,
+          items:        { item: items.map(&:to_savon) }
+        }
+      }
+    end # }}}
+
+
+  end # of class Invoice
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby