clearbooks 0.16.3

data/lib/clearbooks/model/item.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Item model
+  # @brief    Single item from an invoice
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+  class Item < Base
+
+    attr_reader :description, :unit_price, :quantity, :type, :vat, :vat_rate
+
+    # @!attribute [r] description
+    # Required.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] unit_price
+    # Required.
+    # @return [BigDecimal] The unit price of an item in pounds.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] quantity
+    # Required.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] type
+    # Required. The account code identifying the revenue stream.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] vat
+    # Required. The total amount of VAT in pounds. Use either this field or vat_rate.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @!attribute [r] vat_rate
+    # Required. The percentage VAT as a decimal number. Use either this field or vat.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Item model
+    #
+    # @param    [Hash]     data      Item attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
+    def initialize data
+      @description  = data.savon :description
+      @unit_price   = BigDecimal.new data.savon(:unit_price), 2
+      @quantity     = data.savon(:quantity).to_i
+      @type         = data.savon :type
+      @vat          = data.savon :vat
+      @vat_rate     = data.savon :vat_rate
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Item (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+            :@unitPrice     => @unit_price.to_f,
+            :@quantity      => @quantity,
+            :@type          => @type,
+            :@vat           => @vat,
+            :@vat_rate      => @vat_rate,
+            :description    => @description
+      }
+    end # }}}
+
+  end # of class Item
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/journal.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Journal model
+  # @brief    Used to create a new journal via Clearbooks API.
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
+  class Journal < Base
+
+    attr_reader :description, :accounting_date, :entity, :project, :ledgers
+
+    # @!attribute [r] description
+    # Required. The description of the journal.
+    # return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @!attribute [r] accounting_date
+    # Optional. The accounting date of the journal.
+    # return [Date]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @!attribute [r] entity
+    # Optional. The ID of an entity attached to the journal.
+    # return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @!attribute [r] project
+    # Optional. The ID of a project attached to the journal.
+    # return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @!attribute [r] ledgers
+    # Optional. An array of transactions added to the journal. Two items required.
+    # return [Array, Ledger]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Journal model
+    #
+    # @param    [Hash]     data      Journal attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+    def initialize data
+      @description = data.savon :description
+      @accounting_date = parse_date data.savon :accounting_date
+      @entity = data.savon :entity
+      @project = data.savon :project
+      @ledgers = Ledger.build data.savon :ledgers
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Journal (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+        journal: {
+          :@description => @description,
+          :@accountingDate => @accounting_date.strftime('%F'),
+          :@entity => @entity,
+          :@project => @project,
+          :ledgers => @ledgers.map(&:to_savon)
+        }.compact
+      }
+    end # }}}
+
+  end # of class Journal
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/ledger.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Ledger model
+  # @brief    Represents a transaction item in a Journal
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+  class Ledger < Base
+
+    attr_reader :account, :amount
+
+    # @!attribute [r] account
+    # Optional. Account code for associated transaction.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @!attribute [r] amount
+    # Optional. Amount for associated transaction in the journal.
+    # @return [BigDecimal]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Ledger model
+    #
+    # @param    [Hash]     data      Ledger attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
+    def initialize data
+      @account = data.savon :account
+      @amount = BigDecimal.new data.savon :amount
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Ledger (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+        ledger: {
+          :@account => @account,
+          :@amount => @amount.to_f
+        }.compact
+      }
+    end # }}}
+
+  end # of class Ledger
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/payment.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Payment model
+  # @brief    Used to create payments in Clearbooks API
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+  class Payment < Base
+
+    attr_reader :accounting_date,
+                :type,
+                :description,
+                :amount,
+                :entity_id,
+                :payment_method,
+                :bank_account,
+                :invoices
+
+
+    # @!attribute [r] accounting_date
+    # Optional. Date the payment was made.
+    # @return [DateTime]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] type
+    # Optional. String identifying the type of the payment. Value one of: purchases, sales.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] description
+    # Optional.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] amount
+    # Optional. The total amount paid in pounds.
+    # @return [BigDecimal]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] entity_id
+    # Optional. The id of the customer or supplier.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] payment_method
+    # Optional. The id of the payment method.
+    # @return [Fixnum]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] bank_account
+    # Optional. The account code of the bank account being paid into.
+    # @return [String]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @!attribute [r] invoices
+    # Optional. An array of invoice elements.
+    # @return [Array]
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Payment model
+    #
+    # @param    [Hash]     data      Payment attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
+    def initialize data
+      @accounting_date  = parse_date data.savon :accounting_date
+      @type = data.savon :type
+      @description = data.savon :description
+      @amount = BigDecimal.new data.savon :amount
+      @entity_id = data.savon(:entity_id).to_i
+      @payment_method = data.savon(:payment_method).to_i
+      @bank_account = data.savon :bank_account
+      @invoices = data.savon :invoices
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Payment (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+          payment: {
+              :@accountingDate => @accounting_date.strftime('%F'),
+              :@type            => @type,
+              :@amount          => @amount.to_f,
+              :@entityId       => @entity_id,
+              :@paymentMethod  => @payment_method,
+              :@bankAccount    => @bank_account,
+              :description     => @description,
+              :invoices        => { invoice: savon_invoices }
+          }
+      }
+    end # }}}
+
+    private
+
+    def savon_invoices
+      @invoices.map do |i|
+        {
+            :@id      => i[:id],
+            :@amount  => i[:amount]
+        }
+      end
+    end
+
+  end # of class Payment
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/model/project.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+
+# @module     Clearbooks
+# @brief      Handles Ruby idomatic expression of Clear Books SOAP API
+module Clearbooks
+
+  # @class    Clearbooks Project model
+  # @brief    Used to list existing projects or create new.
+  #
+  # @see      https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+  class Project < Base
+
+    attr_reader :id, :description, :project_name, :status
+
+    # @!attribute [r] description
+    # Required. The description of the project.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+
+    # @!attribute [r] project_name
+    # Optional. The name of the project.
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+
+    # @!attribute [r] status
+    # Optional. String identifying the project status. Use one of the following values: "open", "closed" or "deleted".
+    # @see https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+
+    # @fn       def initialize data {{{
+    # @brief    Constructor for Project model
+    #
+    # @param    [Hash]     data      Project attributes. For the list of available options see https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
+    def initialize data
+      @id           = data.savon(:id).to_i
+      @description  = data.savon :description
+      @project_name = data.savon :project_name
+      @status       = data.savon :status
+    end # }}}
+
+    # @fn       def to_savon {{{
+    # @brief    Converts given Project (self) to savon readable format
+    #
+    # @return   [Hash]      Returns self as Savon readable Hash
+    def to_savon
+      {
+        project: {
+          :@projectName => @project_name,
+          :@status => @status,
+          :@description => @description
+        }
+      }
+    end # }}}
+
+
+  end # of class Project
+
+end # of module Clearbooks
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/clearbooks/version.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+
+# @module   Clearbooks Module
+# @brief    Implements the Clearbooks module wrapper around the Clearbooks API
+module Clearbooks
+
+  VERSION = `git describe --tags`.split("-").first || "0.1.0-wrong-version"
+
+end
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/spec/clearbooks/clearbooks_spec.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+# System include
+require 'savon'
+
+# Custom include
+require 'spec_helper'
+
+
+module Clearbooks
+
+  describe Clearbooks do
+
+    describe :config do
+      it 'has default WSDL url' do
+        expect(Clearbooks.config.wsdl).to eq 'https://secure.clearbooks.co.uk/api/wsdl/'
+      end
+
+      it 'has API key' do
+        expect(Clearbooks.config.api_key).not_to be_nil
+      end
+    end
+
+  end # of describe Clearbooks
+
+end # of module Clearbooks
+

data/spec/clearbooks/model/account_code_spec.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+
+# System include
+require 'savon'
+
+# Custom include
+require 'spec_helper'
+
+
+module Clearbooks
+
+  describe Clearbooks do
+
+    before(:all) { savon.mock! }
+    after(:all) { savon.unmock! }
+
+    let(:message) { :any }
+
+    describe '::list_account_codes' do
+      let(:xml) { File.read('spec/fixtures/response/list_account_codes.xml') }
+
+      let(:account_codes) do
+        savon.expects(:list_account_codes).with(message: message).returns(xml)
+        Clearbooks.list_account_codes
+      end
+
+      it 'returns list of account_codes' do
+        expect(account_codes).to be_an Array
+        expect(account_codes.length).to eq 77
+      end
+
+      describe AccountCode do
+        let(:account_code) {account_codes.last}
+
+        it 'has proper attribute values' do
+          expect(account_code.id).to eq 6501001
+          expect(account_code.account_name).to eq 'Corporation tax'
+          expect(account_code.group_name).to eq 'Tax expense'
+          expect(account_code.default_vat_rate).to eq '0.00:Out'
+          expect(account_code.show_sales).to eq false
+          expect(account_code.show_purchases).to eq true
+        end
+
+      end
+
+    end # of describe '::list_account_codes
+
+  end # of describe Clearbooks
+
+end # of module Clearbooks
+