xeroizer 2.15.9 → 2.16.0

data/README.md

@@ -183,7 +183,7 @@ Partner applications are only in beta testing via the Xero API and you will need
 get permission to create a partner application and for them to send you information on obtaining your client-side SSL
 certificate.
 
-Ruby's OpenSSL library rqeuires the certificate and private key to be extracted from the `entrust-client.p12` file
+Ruby's OpenSSL library requires the certificate and private key to be extracted from the `entrust-client.p12` file
 downloaded via Xero's instructions. To extract:
 
 	openssl pkcs12 -in entrust-client.p12 -clcerts -nokeys -out entrust-cert.pem
@@ -391,6 +391,36 @@ invoice = xero.Invoice.find('cd09aa49-134d-40fb-a52b-b63c6a91d712')
 puts "Invoice Contact Name: #{invoice.contact.name}"
 ```
 
+Attachments
+------------
+Files or raw data can be attached to record types
+**attach\_data examples:**
+```ruby
+invoice = xero.Invoice.find('cd09aa49-134d-40fb-a52b-b63c6a91d712')
+invoice.attach_data("example.txt", "This is raw data", "txt")
+```
+
+```ruby
+attach_data('cd09aa49-134d-40fb-a52b-b63c6a91d712', "example.txt", "This is raw data", "txt")
+```
+
+**attach\_file examples:**
+```ruby
+invoice = xero.Invoice.find('cd09aa49-134d-40fb-a52b-b63c6a91d712')
+invoice.attach_file("example.png", "/path/to/image.png", "image/png")
+```
+
+```ruby
+attach_file('cd09aa49-134d-40fb-a52b-b63c6a91d712', "example.png", "/path/to/image.png", "image/png")
+```
+
+**include with online invoice**
+To include an attachment with an invoice set include_online parameter to true within the options hash
+```ruby
+invoice = xero.Invoice.find('cd09aa49-134d-40fb-a52b-b63c6a91d712')
+invoice.attach_file("example.png", "/path/to/image.png", "image/png", { include_online: true })
+```
+
 Creating/Updating Data
 ----------------------
 
@@ -456,6 +486,15 @@ unsaved records aren't valid, it'll return `false` before sending anything acros
 otherwise, it returns `true`. `batch_save` takes one optional argument: the number of records to
 create/update per request. (Defaults to 2,000.)
 
+If you'd rather build and send the records manually, there's a `save_records` method:
+```ruby
+contact1 = xero.Contact.build(some_attributes)
+contact2 = xero.Contact.build(some_other_attributes)
+contact3 = xero.Contact.build(some_more_attributes)
+xero.Contact.save_records([contact1, contact2, contact3])
+```
+It has the same return values as `batch_save`.
+
 ### Errors
 
 If a record doesn't match its internal validation requirements, the `#save` method will return
@@ -561,6 +600,25 @@ client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
                                          :logger => XeroLogger)
 ```
 
+HTTP Callbacks
+--------------------
+
+You can provide "before" and "after" callbacks which will be invoked every
+time Xeroizer makes an HTTP request, which is potentially useful for both
+throttling and logging:
+
+```ruby
+Xeroizer::PublicApplication.new(
+  credentials[:key], credentials[:secret],
+  before_request: ->(request) { puts "Hitting this URL: #{request.url}" },
+  after_request: ->(request, response) { puts "Got this response: #{response.code}" }
+)
+```
+
+The `request` parameter is a custom Struct with `url`, `headers`, `body`,
+and `params` methods. The `response` parameter is a Net::HTTPResponse object.
+
+
 Unit Price Precision
 --------------------
 

data/lib/xeroizer/exceptions.rb

@@ -13,7 +13,10 @@
 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 module Xeroizer
-  class ApiException < StandardError
+  
+  class XeroizerError < StandardError; end
+  
+  class ApiException < XeroizerError
     
     attr_reader :type, :message, :xml, :parsed_xml, :request_body
     
@@ -41,7 +44,7 @@ module Xeroizer
     
   end
   
-  class UnparseableResponse < StandardError
+  class UnparseableResponse < XeroizerError
     
     def initialize(root_element_name)
       @root_element_name = root_element_name
@@ -53,7 +56,7 @@ module Xeroizer
       
   end
   
-  class ObjectNotFound < StandardError
+  class ObjectNotFound < XeroizerError
     
     def initialize(api_endpoint)
       @api_endpoint = api_endpoint
@@ -65,11 +68,11 @@ module Xeroizer
     
   end
   
-  class InvoiceNotFoundError < StandardError; end
+  class InvoiceNotFoundError < XeroizerError; end
 
-  class CreditNoteNotFoundError < StandardError; end
+  class CreditNoteNotFoundError < XeroizerError; end
   
-  class MethodNotAllowed < StandardError
+  class MethodNotAllowed < XeroizerError
     
     def initialize(klass, method)
       @klass = klass
@@ -82,7 +85,7 @@ module Xeroizer
     
   end
   
-  class RecordKeyMustBeDefined < StandardError
+  class RecordKeyMustBeDefined < XeroizerError
     
     def initialize(possible_keys)
       @possible_keys = possible_keys
@@ -94,7 +97,7 @@ module Xeroizer
     
   end
 
-  class SettingTotalDirectlyNotSupported < StandardError
+  class SettingTotalDirectlyNotSupported < XeroizerError
     
     def initialize(attribute_name)
       @attribute_name = attribute_name
@@ -106,7 +109,7 @@ module Xeroizer
     
   end
 
-  class InvalidAttributeInWhere < StandardError
+  class InvalidAttributeInWhere < XeroizerError
     
     def initialize(model_name, attribute_name)
       @model_name = model_name
@@ -119,7 +122,7 @@ module Xeroizer
     
   end
   
-  class AssociationTypeMismatch < StandardError
+  class AssociationTypeMismatch < XeroizerError
     
     def initialize(model_class, actual_class)
       @model_class = model_class
@@ -132,7 +135,7 @@ module Xeroizer
     
   end
 
-  class CannotChangeInvoiceStatus < StandardError
+  class CannotChangeInvoiceStatus < XeroizerError
 
     def initialize(invoice, new_status)
       @invoice = invoice

data/lib/xeroizer/generic_application.rb

@@ -6,12 +6,14 @@ module Xeroizer
     include Http
     extend Record::ApplicationHelper
 
-    attr_reader :client, :xero_url, :logger, :rate_limit_sleep, :rate_limit_max_attempts, :default_headers, :unitdp
+    attr_reader :client, :xero_url, :logger, :rate_limit_sleep, :rate_limit_max_attempts,
+                :default_headers, :unitdp, :before_request, :after_request
 
     extend Forwardable
     def_delegators :client, :access_token
 
     record :Account
+    record :Allocation
     record :Attachment
     record :BrandingTheme
     record :Contact
@@ -26,7 +28,10 @@ module Xeroizer
     record :ManualJournal
     record :Organisation
     record :Payment
+    record :Prepayment
     record :Receipt
+    record :RepeatingInvoice
+    record :Schedule
     record :TaxRate
     record :TrackingCategory
     record :TrackingCategoryChild
@@ -54,6 +59,8 @@ module Xeroizer
         @rate_limit_sleep = options[:rate_limit_sleep] || false
         @rate_limit_max_attempts = options[:rate_limit_max_attempts] || 5
         @default_headers = options[:default_headers] || {}
+        @before_request = options.delete(:before_request)
+        @after_request = options.delete(:after_request)
         @client   = OAuth.new(consumer_key, consumer_secret, options.merge({default_headers: default_headers}))
         @logger = options[:logger] || false
         @unitdp = options[:unitdp] || 2

data/lib/xeroizer/http.rb

@@ -15,6 +15,7 @@
 module Xeroizer
   module Http
     class BadResponse < StandardError; end
+    RequestInfo = Struct.new(:url, :headers, :params, :body)
 
     ACCEPT_MIME_MAP = {
       :pdf  => 'application/pdf',
@@ -57,9 +58,9 @@ module Xeroizer
 
         headers = self.default_headers.merge({ 'charset' => 'utf-8' })
 
-        # include the unitdp query string parameter 
+        # include the unitdp query string parameter
         params.merge!(unitdp_param(url))
-        
+
         if method != :get
           headers['Content-Type'] ||= "application/x-www-form-urlencoded"
         end
@@ -84,10 +85,13 @@ module Xeroizer
           url += "?" + params.map {|key,value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
         end
 
-        uri   = URI.parse(url)
+        uri = URI.parse(url)
 
         attempts = 0
 
+        request_info = RequestInfo.new(url, headers, params, body)
+        before_request.call(request_info) if before_request
+
         begin
           attempts += 1
           logger.info("XeroGateway Request: #{method.to_s.upcase} #{uri.request_uri}") if self.logger
@@ -100,12 +104,8 @@ module Xeroizer
             when :put   then    client.put(uri.request_uri, raw_body, headers)
           end
 
-          if self.logger
-            logger.info("XeroGateway Response (#{response.code})")
-            unless response.code.to_i == 200
-              logger.info("#{uri.request_uri}\n== Response Body\n\n#{response.plain_body}\n== End Response Body")
-            end
-          end
+          log_response(response, uri)
+          after_request.call(request_info, response) if after_request
 
           case response.code.to_i
             when 200
@@ -133,7 +133,16 @@ module Xeroizer
         end
       end
 
-      def handle_oauth_error!(response)
+    def log_response(response, uri)
+      if self.logger
+        logger.info("XeroGateway Response (#{response.code})")
+        logger.add(response.code.to_i == 200 ? Logger::DEBUG : Logger::INFO) {
+          "#{uri.request_uri}\n== Response Body\n\n#{response.plain_body}\n== End Response Body"
+        }
+      end
+    end
+
+    def handle_oauth_error!(response)
         error_details = CGI.parse(response.plain_body)
         description   = error_details["oauth_problem_advice"].first
         problem = error_details["oauth_problem"].first

data/lib/xeroizer/models/attachment.rb

@@ -4,12 +4,12 @@ module Xeroizer
     class AttachmentModel < BaseModel
 
       module Extensions
-        def attach_data(id, filename, data, content_type = "application/octet-stream")
-          application.Attachment.attach_data(url, id, filename, data, content_type)
+        def attach_data(id, filename, data, content_type = "application/octet-stream", options = {})
+          application.Attachment.attach_data(url, id, filename, data, content_type, options)
         end
 
-        def attach_file(id, filename, path, content_type = "application/octet-stream")
-          application.Attachment.attach_file(url, id, filename, path, content_type)
+        def attach_file(id, filename, path, content_type = "application/octet-stream", options = {})
+          application.Attachment.attach_file(url, id, filename, path, content_type, options)
         end
 
         def attachments(id)
@@ -19,11 +19,13 @@ module Xeroizer
 
       set_permissions :read
 
-      def attach_data(url, id, filename, data, content_type)
+      def attach_data(url, id, filename, data, content_type, options = {})
+        options = { include_online: false }.merge(options)
+
         response_xml = @application.http_put(@application.client,
                                               "#{url}/#{CGI.escape(id)}/Attachments/#{CGI.escape(filename)}",
                                               data,
-                                              :raw_body => true, :content_type => content_type
+                                              :raw_body => true, :content_type => content_type, "IncludeOnline" => options[:include_online]
                                              )
         response = parse_response(response_xml)
         if (response_items = response.response_items) && response_items.size > 0
@@ -33,8 +35,8 @@ module Xeroizer
         end
       end
 
-      def attach_file(url, id, filename, path, content_type)
-        attach_data(url, id, filename, File.read(path), content_type)
+      def attach_file(url, id, filename, path, content_type, options = {})
+        attach_data(url, id, filename, File.read(path), content_type, options)
       end
 
       def attachments_for(url, id)
@@ -54,12 +56,12 @@ module Xeroizer
     class Attachment < Base
 
       module Extensions
-        def attach_file(filename, path, content_type = "application/octet-stream")
-          parent.attach_file(id, filename, path, content_type)
+        def attach_file(filename, path, content_type = "application/octet-stream", options = {})
+          parent.attach_file(id, filename, path, content_type, options)
         end
 
-        def attach_data(filename, data, content_type = "application/octet-stream")
-          parent.attach_data(id, filename, data, content_type)
+        def attach_data(filename, data, content_type = "application/octet-stream", options = {})
+          parent.attach_data(id, filename, data, content_type, options)
         end
 
         def attachments
@@ -90,4 +92,4 @@ module Xeroizer
     end
 
   end
-end
+end

data/lib/xeroizer/models/bank_transaction.rb

@@ -38,12 +38,14 @@ module Xeroizer
       string        :bank_transaction_id, :api_name => "BankTransactionID"
       boolean       :is_reconciled
       string        :status
+      string        :currency_code
+      decimal       :currency_rate
 
       alias_method :reconciled?, :is_reconciled
 
       belongs_to :contact, :model_name => 'Contact'
       string :line_amount_types
-      has_many :line_items, :model_name => 'LineItem'
+      has_many :line_items, :model_name => 'LineItem', :complete_on_page => true
       belongs_to :bank_account, :model_name => 'BankAccount'
 
       validates_inclusion_of :line_amount_types,

data/lib/xeroizer/models/branding_theme.rb

@@ -14,7 +14,7 @@ module Xeroizer
       guid      :branding_theme_id
       string    :name
       integer   :sort_order
-      datetime  :created_date_utc, :api_name => 'CreatedDateUTC'
+      datetime_utc  :created_date_utc, :api_name => 'CreatedDateUTC'
 
     end
     

data/lib/xeroizer/models/contact.rb

@@ -36,10 +36,12 @@ module Xeroizer
       string        :skype_user_name
       string        :contact_groups
       string        :default_currency
+      string        :purchases_default_account_code 
+      string        :sales_default_account_code 
       datetime_utc  :updated_date_utc, :api_name => 'UpdatedDateUTC'
       boolean       :is_supplier
       boolean       :is_customer
-
+      
       has_many  :addresses, :list_complete => true
       has_many  :phones, :list_complete => true
       has_many  :contact_groups

data/lib/xeroizer/models/credit_note.rb

@@ -126,8 +126,32 @@ module Xeroizer
         def pdf(filename = nil)
           parent.pdf(id, filename)
         end
-              
+
+        def save
+          # Calling parse_save_response() on the credit note will wipe out
+          # the allocations, so we have to manually preserve them.
+          allocations_backup = self.allocations
+          if super
+            self.allocations = allocations_backup
+            allocate unless self.allocations.empty?
+            true
+          end
+        end
+
+        def allocate
+          if self.class.possible_primary_keys && self.class.possible_primary_keys.all? { | possible_key | self[possible_key].nil? }
+            raise RecordKeyMustBeDefined.new(self.class.possible_primary_keys)
+          end
+
+          request = association_to_xml(:allocations)
+          allocations_url = "#{parent.url}/#{CGI.escape(id)}/Allocations"
+
+          log "[ALLOCATION SENT] (#{__FILE__}:#{__LINE__}) \r\n#{request}"
+          response = parent.application.http_put(parent.application.client, allocations_url, request)
+          log "[ALLOCATION RECEIVED] (#{__FILE__}:#{__LINE__}) \r\n#{response}"
+          parse_save_response(response)
+        end
     end
-    
+
   end
 end

data/lib/xeroizer/models/employee.rb

@@ -17,12 +17,57 @@ module Xeroizer
       string  :status
       string  :first_name
       string  :last_name
+      date    :date_of_birth
 
-      belongs_to  :external_link
+      # Optional attributes
+      string  :gender # M or F
+      string  :email
+      string  :phone # (max length = 50, but AU only?)
+      string  :mobile # (max length = 50)
+      date    :start_date
+      date    :termination_date
+      boolean :is_authorised_to_approve_timesheets
+      string  :employee_group_name
 
-      validates_presence_of :first_name, :last_name
+      datetime_utc  :updated_date_utc, :api_name => 'UpdatedDateUTC'
       
+      belongs_to  :external_link
+
+      validates_presence_of :first_name, :last_name, :date_of_birth
+
     end
-    
+
+  #   # AU Only API
+  #   class EmployeeAU < Employee
+  #     string :occupation
+  #     string :classification # length: 100
+  #     string :ordinary_earnings_rate_id
+  #     boolean :is_authorised_to_approve_leave
+
+  #     string :title # (max length = 10)
+  #     string :twitter_user_name # (max length = 50)
+  #     # PayrollCalendarID Xero unique identifier for payroll calendar for the employee
+  #     # BankAccounts  See BankAccount
+  #     # SuperMemberships  See SuperMemberships
+  #   end
+
+  #   # US Only API
+  #   class EmployeeUS < Employee
+  #     string :middle_names #max length = 35
+  #     string :job_title
+  #     string :employee_number
+  #     string :social_security_number # (xxx-xx-xxxx)
+  #     string :holiday_group_id
+  #     string :pay_schedule_id
+  #     string :employment_basis  # One of http://developer.xero.com/documentation/payroll-api-us/Types-Codes/#EmploymentBasis
+  #     boolean :is_authorised_to_approve_time_off
+
+  #     # MailingAddress - US only, has_one relationship
+  #     # SalaryAndWages  See SalaryAndWages
+  #     # WorkLocations See WorkLocations
+  #     # PaymentMethod See PaymentMethods
+  #     # PayTemplate See PayTemplate
+  #     # OpeningBalances See OpeningBalances
+  #   end
   end
-end
+end

data/lib/xeroizer/models/invoice.rb

@@ -78,7 +78,7 @@ module Xeroizer
       boolean      :has_attachments
 
       belongs_to   :contact
-      has_many     :line_items
+      has_many     :line_items, :complete_on_page => true
       has_many     :payments
       has_many     :credit_notes
 

data/lib/xeroizer/models/journal.rb

@@ -14,8 +14,10 @@ module Xeroizer
       guid      :journal_id
       date      :journal_date, :internal_name => :date
       string    :journal_number
-      datetime  :created_date_utc, :api_name => 'CreatedDateUTC'
+      datetime_utc  :created_date_utc, :api_name => 'CreatedDateUTC'
       string    :reference
+      guid      :source_id
+      string    :source_type
       
       has_many  :journal_lines
        

data/lib/xeroizer/models/journal_line.rb

@@ -19,6 +19,7 @@ module Xeroizer
       decimal  :tax_amount
       string   :tax_type
       string   :tax_name
+      string   :description
 
       has_many :tracking_categories, :model_name => 'JournalLineTrackingCategory'
        

data/lib/xeroizer/models/journal_line_tracking_category.rb

@@ -13,8 +13,9 @@ module Xeroizer
       string  :name
       string  :option
       guid    :tracking_category_id
+      guid    :tracking_option_id
       
     end
     
   end
-end
+end

data/lib/xeroizer/models/line_item.rb

@@ -19,6 +19,7 @@ module Xeroizer
       decimal :tax_amount
       decimal :line_amount, :calculated => true
       decimal :discount_rate
+      string  :line_item_id
       
       has_many  :tracking, :model_name => 'TrackingCategoryChild'
       

data/lib/xeroizer/models/manual_journal.rb

@@ -29,7 +29,7 @@ module Xeroizer
       boolean       :show_on_cash_basis_reports
       datetime_utc  :updated_date_utc, :api_name => 'UpdatedDateUTC'
       
-      has_many      :journal_lines, :model_name => 'ManualJournalLine'
+      has_many      :journal_lines, :model_name => 'ManualJournalLine', :complete_on_page => true
       
       validates_presence_of :narration
       validates_associated :journal_lines

data/lib/xeroizer/models/organisation.rb

@@ -10,6 +10,28 @@ module Xeroizer
     
     class Organisation < Base
       
+      SALES_TAX_BASIS = {
+        'NZ' => 
+          {'PAYMENTS' => 'Payments Basis',
+           'INVOICE' => 'Invoice Basis',
+           'NONE' => 'None'},
+        'GB' => 
+          {
+            'CASH' => 'Cash Scheme',
+            'ACCRUAL' => 'Accrual Scheme',
+            'FLATRATECASH' => 'Flate Rate Cash Scheme',
+            'NONE' => 'None'
+          },
+        'GLOBAL' =>
+          {
+            'CASH' => 'Cash Basis',
+            'ACCRUALS' => 'Accruals Basis',
+            'NONE' => 'None'
+          }
+      } unless defined?(SALES_TAX_BASES)
+
+      SALES_TAX_BASES = SALES_TAX_BASIS.values.map(&:keys).flatten.sort
+      
       string    :api_key, :api_name => 'APIKey'
       string    :name
       string    :legal_name
@@ -23,16 +45,34 @@ module Xeroizer
       string    :organisation_status
       integer   :financial_year_end_day
       integer   :financial_year_end_month
+      string    :sales_tax_basis
+      string    :sales_tax_period
       date      :period_lock_date
       date      :end_of_year_lock_date
       string    :tax_number
       string    :registration_number
       string    :timezone
-      datetime  :created_date_utc, :api_name => 'CreatedDateUTC'
+      datetime_utc  :created_date_utc, :api_name => 'CreatedDateUTC'
+      string    :sales_tax_basis
+      string    :sales_tax_period
 
       has_many :addresses
       has_many :phones
 
+      validates :sales_tax_basis, :message => "is not a valid option" do
+        valid = true
+        if sales_tax_basis
+
+          valid_bases = (SALES_TAX_BASIS[country_code] || SALES_TAX_BASIS['GLOBAL']).keys
+
+          unless valid_bases.include?(sales_tax_basis)
+            valid = false
+          end
+        end
+        
+        valid
+      end
+
     end
     
   end

data/lib/xeroizer/models/phone.rb

@@ -18,7 +18,8 @@ module Xeroizer
       string :phone_number, :internal_name => :number
       string :phone_area_code, :internal_name => :area_code
       string :phone_country_code, :internal_name => :country_code
-      
+
+      validates_length_of :phone_number, :max => 50
     end
     
   end

data/lib/xeroizer/models/prepayment.rb

@@ -0,0 +1,39 @@
+module Xeroizer
+  module Record
+
+    class PrepaymentModel < BaseModel
+
+      set_xml_root_name 'Prepayments'
+      set_permissions :read
+
+    end
+
+    class Prepayment < Base
+      set_primary_key :prepayment_id
+
+      guid          :prepayment_id
+      date          :date
+      string        :status
+      string        :line_amount_types
+      decimal       :sub_total
+      decimal       :total_tax
+      decimal       :total
+      datetime_utc  :updated_date_utc, :api_name => 'UpdatedDateUTC'
+      string        :currency_code
+      datetime_utc  :fully_paid_on_date
+      string        :type
+      string        :reference
+      decimal       :currency_rate
+      decimal       :remaining_credit
+      boolean       :has_attachments
+
+      belongs_to    :contact
+      has_many      :line_items
+
+      def contact_id
+        contact.id if contact
+      end
+
+    end
+  end
+end