xero-kiwi 0.1.0

data/lib/xero_kiwi/accounting/branding_theme.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "time"
+
+module XeroKiwi
+  module Accounting
+    # Represents a Xero Branding Theme returned by the Accounting API.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/brandingthemes
+    class BrandingTheme
+      ATTRIBUTES = {
+        branding_theme_id: "BrandingThemeID",
+        name:              "Name",
+        logo_url:          "LogoUrl",
+        type:              "Type",
+        sort_order:        "SortOrder",
+        created_date_utc:  "CreatedDateUTC"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def self.from_response(payload)
+        return [] if payload.nil?
+
+        items = payload["BrandingThemes"]
+        return [] if items.nil?
+
+        items.map { |attrs| new(attrs) }
+      end
+
+      def initialize(attrs)
+        attrs              = attrs.transform_keys(&:to_s)
+        @branding_theme_id = attrs["BrandingThemeID"]
+        @name              = attrs["Name"]
+        @logo_url          = attrs["LogoUrl"]
+        @type              = attrs["Type"]
+        @sort_order        = attrs["SortOrder"]
+        @created_date_utc  = parse_time(attrs["CreatedDateUTC"])
+      end
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(BrandingTheme) && other.branding_theme_id == branding_theme_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, branding_theme_id].hash
+
+      def inspect
+        "#<#{self.class} branding_theme_id=#{branding_theme_id.inspect} " \
+          "name=#{name.inspect} type=#{type.inspect}>"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return nil if str.empty?
+
+        if (match = str.match(%r{\A/Date\((\d+)([+-]\d{4})?\)/\z}))
+          Time.at(match[1].to_i / 1000.0).utc
+        else
+          str = "#{str}Z" unless str.match?(/[Zz]\z|[+-]\d{2}:?\d{2}\z/)
+          Time.iso8601(str)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/contact.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "time"
+
+module XeroKiwi
+  module Accounting
+    # Represents a Xero Contact returned by the Accounting API.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/contacts
+    class Contact
+      ATTRIBUTES = {
+        contact_id:                         "ContactID",
+        contact_number:                     "ContactNumber",
+        account_number:                     "AccountNumber",
+        contact_status:                     "ContactStatus",
+        name:                               "Name",
+        first_name:                         "FirstName",
+        last_name:                          "LastName",
+        email_address:                      "EmailAddress",
+        bank_account_details:               "BankAccountDetails",
+        company_number:                     "CompanyNumber",
+        tax_number:                         "TaxNumber",
+        tax_number_type:                    "TaxNumberType",
+        accounts_receivable_tax_type:       "AccountsReceivableTaxType",
+        accounts_payable_tax_type:          "AccountsPayableTaxType",
+        addresses:                          "Addresses",
+        phones:                             "Phones",
+        is_supplier:                        "IsSupplier",
+        is_customer:                        "IsCustomer",
+        default_currency:                   "DefaultCurrency",
+        updated_date_utc:                   "UpdatedDateUTC",
+        contact_persons:                    "ContactPersons",
+        xero_network_key:                   "XeroNetworkKey",
+        merged_to_contact_id:               "MergedToContactID",
+        sales_default_account_code:         "SalesDefaultAccountCode",
+        purchases_default_account_code:     "PurchasesDefaultAccountCode",
+        sales_tracking_categories:          "SalesTrackingCategories",
+        purchases_tracking_categories:      "PurchasesTrackingCategories",
+        sales_default_line_amount_type:     "SalesDefaultLineAmountType",
+        purchases_default_line_amount_type: "PurchasesDefaultLineAmountType",
+        tracking_category_name:             "TrackingCategoryName",
+        tracking_option_name:               "TrackingOptionName",
+        payment_terms:                      "PaymentTerms",
+        contact_groups:                     "ContactGroups",
+        website:                            "Website",
+        branding_theme:                     "BrandingTheme",
+        batch_payments:                     "BatchPayments",
+        discount:                           "Discount",
+        balances:                           "Balances",
+        has_attachments:                    "HasAttachments"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def self.from_response(payload)
+        return [] if payload.nil?
+
+        items = payload["Contacts"]
+        return [] if items.nil?
+
+        items.map { |attrs| new(attrs) }
+      end
+
+      def initialize(attrs, reference: false) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        attrs                               = attrs.transform_keys(&:to_s)
+        @is_reference                       = reference
+        @contact_id                         = attrs["ContactID"]
+        @contact_number                     = attrs["ContactNumber"]
+        @account_number                     = attrs["AccountNumber"]
+        @contact_status                     = attrs["ContactStatus"]
+        @name                               = attrs["Name"]
+        @first_name                         = attrs["FirstName"]
+        @last_name                          = attrs["LastName"]
+        @email_address                      = attrs["EmailAddress"]
+        @bank_account_details               = attrs["BankAccountDetails"]
+        @company_number                     = attrs["CompanyNumber"]
+        @tax_number                         = attrs["TaxNumber"]
+        @tax_number_type                    = attrs["TaxNumberType"]
+        @accounts_receivable_tax_type       = attrs["AccountsReceivableTaxType"]
+        @accounts_payable_tax_type          = attrs["AccountsPayableTaxType"]
+        @addresses                          = (attrs["Addresses"] || []).map { |a| Address.new(a) }
+        @phones                             = (attrs["Phones"] || []).map { |p| Phone.new(p) }
+        @is_supplier                        = attrs["IsSupplier"]
+        @is_customer                        = attrs["IsCustomer"]
+        @default_currency                   = attrs["DefaultCurrency"]
+        @updated_date_utc                   = parse_time(attrs["UpdatedDateUTC"])
+        @contact_persons                    = (attrs["ContactPersons"] || []).map { |cp| ContactPerson.new(cp) }
+        @xero_network_key                   = attrs["XeroNetworkKey"]
+        @merged_to_contact_id               = attrs["MergedToContactID"]
+        @sales_default_account_code         = attrs["SalesDefaultAccountCode"]
+        @purchases_default_account_code     = attrs["PurchasesDefaultAccountCode"]
+        @sales_tracking_categories          = (attrs["SalesTrackingCategories"] || []).map { |t| TrackingCategory.new(t) }
+        @purchases_tracking_categories      = (attrs["PurchasesTrackingCategories"] || []).map { |t| TrackingCategory.new(t) }
+        @sales_default_line_amount_type     = attrs["SalesDefaultLineAmountType"]
+        @purchases_default_line_amount_type = attrs["PurchasesDefaultLineAmountType"]
+        @tracking_category_name             = attrs["TrackingCategoryName"]
+        @tracking_option_name               = attrs["TrackingOptionName"]
+        @payment_terms                      = PaymentTerms.from_hash(attrs["PaymentTerms"])
+        @contact_groups                     = (attrs["ContactGroups"] || []).map { |cg| ContactGroup.new(cg, reference: true) }
+        @website                            = attrs["Website"]
+        @branding_theme                     = attrs["BrandingTheme"] ? BrandingTheme.new(attrs["BrandingTheme"]) : nil
+        @batch_payments                     = attrs["BatchPayments"]
+        @discount                           = attrs["Discount"]
+        @balances                           = attrs["Balances"]
+        @has_attachments                    = attrs["HasAttachments"]
+      end
+
+      def reference? = @is_reference
+
+      def supplier? = is_supplier == true
+
+      def customer? = is_customer == true
+
+      def active? = contact_status == "ACTIVE"
+
+      def archived? = contact_status == "ARCHIVED"
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(Contact) && other.contact_id == contact_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, contact_id].hash
+
+      def inspect
+        "#<#{self.class} contact_id=#{contact_id.inspect} " \
+          "name=#{name.inspect} contact_status=#{contact_status.inspect}>"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return nil if str.empty?
+
+        if (match = str.match(%r{\A/Date\((\d+)([+-]\d{4})?\)/\z}))
+          Time.at(match[1].to_i / 1000.0).utc
+        else
+          str = "#{str}Z" unless str.match?(/[Zz]\z|[+-]\d{2}:?\d{2}\z/)
+          Time.iso8601(str)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/contact_group.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Accounting
+    # Represents a Xero Contact Group returned by the Accounting API.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/contactgroups
+    class ContactGroup
+      ATTRIBUTES = {
+        contact_group_id: "ContactGroupID",
+        name:             "Name",
+        status:           "Status",
+        contacts:         "Contacts"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def self.from_response(payload)
+        return [] if payload.nil?
+
+        items = payload["ContactGroups"]
+        return [] if items.nil?
+
+        items.map { |attrs| new(attrs) }
+      end
+
+      def initialize(attrs, reference: false)
+        attrs             = attrs.transform_keys(&:to_s)
+        @is_reference     = reference
+        @contact_group_id = attrs["ContactGroupID"]
+        @name             = attrs["Name"]
+        @status           = attrs["Status"]
+        @contacts         = (attrs["Contacts"] || []).map { |c| Contact.new(c, reference: true) }
+      end
+
+      def reference? = @is_reference
+
+      def active? = status == "ACTIVE"
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(ContactGroup) && other.contact_group_id == contact_group_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, contact_group_id].hash
+
+      def inspect
+        "#<#{self.class} contact_group_id=#{contact_group_id.inspect} " \
+          "name=#{name.inspect} status=#{status.inspect}>"
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/contact_person.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Accounting
+    # Represents a contact person nested within a Xero Contact.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/contacts
+    class ContactPerson
+      ATTRIBUTES = {
+        first_name:        "FirstName",
+        last_name:         "LastName",
+        email_address:     "EmailAddress",
+        include_in_emails: "IncludeInEmails"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def initialize(attrs)
+        attrs              = attrs.transform_keys(&:to_s)
+        @first_name        = attrs["FirstName"]
+        @last_name         = attrs["LastName"]
+        @email_address     = attrs["EmailAddress"]
+        @include_in_emails = attrs["IncludeInEmails"]
+      end
+
+      def include_in_emails? = include_in_emails == true
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(ContactPerson) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash = to_h.hash
+
+      def inspect
+        "#<#{self.class} first_name=#{first_name.inspect} " \
+          "last_name=#{last_name.inspect} email_address=#{email_address.inspect}>"
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/credit_note.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "time"
+
+module XeroKiwi
+  module Accounting
+    # Represents a Xero Credit Note returned by the Accounting API.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/creditnotes
+    class CreditNote
+      ATTRIBUTES = {
+        credit_note_id:     "CreditNoteID",
+        credit_note_number: "CreditNoteNumber",
+        type:               "Type",
+        contact:            "Contact",
+        date:               "Date",
+        status:             "Status",
+        line_amount_types:  "LineAmountTypes",
+        line_items:         "LineItems",
+        sub_total:          "SubTotal",
+        total_tax:          "TotalTax",
+        total:              "Total",
+        cis_deduction:      "CISDeduction",
+        updated_date_utc:   "UpdatedDateUTC",
+        currency_code:      "CurrencyCode",
+        currency_rate:      "CurrencyRate",
+        fully_paid_on_date: "FullyPaidOnDate",
+        reference:          "Reference",
+        sent_to_contact:    "SentToContact",
+        remaining_credit:   "RemainingCredit",
+        allocations:        "Allocations",
+        branding_theme_id:  "BrandingThemeID",
+        has_attachments:    "HasAttachments"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def self.from_response(payload)
+        return [] if payload.nil?
+
+        items = payload["CreditNotes"]
+        return [] if items.nil?
+
+        items.map { |attrs| new(attrs) }
+      end
+
+      def initialize(attrs, reference: false) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        attrs                = attrs.transform_keys(&:to_s)
+        @is_reference        = reference
+        @credit_note_id      = attrs["CreditNoteID"]
+        @credit_note_number  = attrs["CreditNoteNumber"]
+        @type                = attrs["Type"]
+        @contact             = attrs["Contact"] ? Contact.new(attrs["Contact"], reference: true) : nil
+        @date                = parse_time(attrs["Date"])
+        @status              = attrs["Status"]
+        @line_amount_types   = attrs["LineAmountTypes"]
+        @line_items          = (attrs["LineItems"] || []).map { |li| LineItem.new(li) }
+        @sub_total           = attrs["SubTotal"]
+        @total_tax           = attrs["TotalTax"]
+        @total               = attrs["Total"]
+        @cis_deduction       = attrs["CISDeduction"]
+        @updated_date_utc    = parse_time(attrs["UpdatedDateUTC"])
+        @currency_code       = attrs["CurrencyCode"]
+        @currency_rate       = attrs["CurrencyRate"]
+        @fully_paid_on_date  = parse_time(attrs["FullyPaidOnDate"])
+        @reference           = attrs["Reference"]
+        @sent_to_contact     = attrs["SentToContact"]
+        @remaining_credit    = attrs["RemainingCredit"]
+        @allocations         = (attrs["Allocations"] || []).map { |a| Allocation.new(a) }
+        @branding_theme_id   = attrs["BrandingThemeID"]
+        @has_attachments     = attrs["HasAttachments"]
+      end
+
+      def accounts_receivable? = type == "ACCRECCREDIT"
+
+      def reference? = @is_reference
+
+      def accounts_payable? = type == "ACCPAYCREDIT"
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(CreditNote) && other.credit_note_id == credit_note_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, credit_note_id].hash
+
+      def inspect
+        "#<#{self.class} credit_note_id=#{credit_note_id.inspect} " \
+          "type=#{type.inspect} status=#{status.inspect} total=#{total.inspect}>"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return nil if str.empty?
+
+        if (match = str.match(%r{\A/Date\((\d+)([+-]\d{4})?\)/\z}))
+          Time.at(match[1].to_i / 1000.0).utc
+        else
+          str = "#{str}Z" unless str.match?(/[Zz]\z|[+-]\d{2}:?\d{2}\z/)
+          Time.iso8601(str)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/external_link.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Accounting
+    # A Xero external link (social/web profile). Used by Organisation.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/types#externallinks
+    class ExternalLink
+      ATTRIBUTES = {
+        link_type: "LinkType",
+        url:       "Url"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def initialize(attrs)
+        attrs      = attrs.transform_keys(&:to_s)
+        @link_type = attrs["LinkType"]
+        @url       = attrs["Url"]
+      end
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(ExternalLink) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash = to_h.hash
+
+      def inspect
+        "#<#{self.class} type=#{link_type.inspect} url=#{url.inspect}>"
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/invoice.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "time"
+
+module XeroKiwi
+  module Accounting
+    # Represents a Xero Invoice returned by the Accounting API.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/invoices
+    class Invoice
+      ATTRIBUTES = {
+        invoice_id:                      "InvoiceID",
+        invoice_number:                  "InvoiceNumber",
+        type:                            "Type",
+        contact:                         "Contact",
+        date:                            "Date",
+        due_date:                        "DueDate",
+        status:                          "Status",
+        line_amount_types:               "LineAmountTypes",
+        line_items:                      "LineItems",
+        sub_total:                       "SubTotal",
+        total_tax:                       "TotalTax",
+        total:                           "Total",
+        total_discount:                  "TotalDiscount",
+        updated_date_utc:                "UpdatedDateUTC",
+        currency_code:                   "CurrencyCode",
+        currency_rate:                   "CurrencyRate",
+        reference:                       "Reference",
+        branding_theme_id:               "BrandingThemeID",
+        url:                             "Url",
+        sent_to_contact:                 "SentToContact",
+        expected_payment_date:           "ExpectedPaymentDate",
+        planned_payment_date:            "PlannedPaymentDate",
+        has_attachments:                 "HasAttachments",
+        repeating_invoice_id:            "RepeatingInvoiceID",
+        payments:                        "Payments",
+        credit_notes:                    "CreditNotes",
+        prepayments:                     "Prepayments",
+        overpayments:                    "Overpayments",
+        amount_due:                      "AmountDue",
+        amount_paid:                     "AmountPaid",
+        amount_credited:                 "AmountCredited",
+        cis_deduction:                   "CISDeduction",
+        fully_paid_on_date:              "FullyPaidOnDate",
+        sales_tax_calculation_type_code: "SalesTaxCalculationTypeCode",
+        invoice_addresses:               "InvoiceAddresses"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def self.from_response(payload)
+        return [] if payload.nil?
+
+        items = payload["Invoices"]
+        return [] if items.nil?
+
+        items.map { |attrs| new(attrs) }
+      end
+
+      def initialize(attrs, reference: false) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        attrs                            = attrs.transform_keys(&:to_s)
+        @is_reference                    = reference
+        @invoice_id                      = attrs["InvoiceID"]
+        @invoice_number                  = attrs["InvoiceNumber"]
+        @type                            = attrs["Type"]
+        @contact                         = attrs["Contact"] ? Contact.new(attrs["Contact"], reference: true) : nil
+        @date                            = parse_time(attrs["Date"])
+        @due_date                        = parse_time(attrs["DueDate"])
+        @status                          = attrs["Status"]
+        @line_amount_types               = attrs["LineAmountTypes"]
+        @line_items                      = (attrs["LineItems"] || []).map { |li| LineItem.new(li) }
+        @sub_total                       = attrs["SubTotal"]
+        @total_tax                       = attrs["TotalTax"]
+        @total                           = attrs["Total"]
+        @total_discount                  = attrs["TotalDiscount"]
+        @updated_date_utc                = parse_time(attrs["UpdatedDateUTC"])
+        @currency_code                   = attrs["CurrencyCode"]
+        @currency_rate                   = attrs["CurrencyRate"]
+        @reference                       = attrs["Reference"]
+        @branding_theme_id               = attrs["BrandingThemeID"]
+        @url                             = attrs["Url"]
+        @sent_to_contact                 = attrs["SentToContact"]
+        @expected_payment_date           = parse_time(attrs["ExpectedPaymentDate"])
+        @planned_payment_date            = parse_time(attrs["PlannedPaymentDate"])
+        @has_attachments                 = attrs["HasAttachments"]
+        @repeating_invoice_id            = attrs["RepeatingInvoiceID"]
+        @payments                        = (attrs["Payments"] || []).map { |p| Payment.new(p, reference: true) }
+        @credit_notes                    = (attrs["CreditNotes"] || []).map { |cn| CreditNote.new(cn, reference: true) }
+        @prepayments                     = (attrs["Prepayments"] || []).map { |p| Prepayment.new(p, reference: true) }
+        @overpayments                    = (attrs["Overpayments"] || []).map { |o| Overpayment.new(o, reference: true) }
+        @amount_due                      = attrs["AmountDue"]
+        @amount_paid                     = attrs["AmountPaid"]
+        @amount_credited                 = attrs["AmountCredited"]
+        @cis_deduction                   = attrs["CISDeduction"]
+        @fully_paid_on_date              = parse_time(attrs["FullyPaidOnDate"])
+        @sales_tax_calculation_type_code = attrs["SalesTaxCalculationTypeCode"]
+        @invoice_addresses               = attrs["InvoiceAddresses"] || []
+      end
+
+      def reference? = @is_reference
+
+      def accounts_receivable? = type == "ACCREC"
+
+      def accounts_payable? = type == "ACCPAY"
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(Invoice) && other.invoice_id == invoice_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, invoice_id].hash
+
+      def inspect
+        "#<#{self.class} invoice_id=#{invoice_id.inspect} " \
+          "invoice_number=#{invoice_number.inspect} type=#{type.inspect} " \
+          "status=#{status.inspect} total=#{total.inspect}>"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return nil if str.empty?
+
+        if (match = str.match(%r{\A/Date\((\d+)([+-]\d{4})?\)/\z}))
+          Time.at(match[1].to_i / 1000.0).utc
+        else
+          str = "#{str}Z" unless str.match?(/[Zz]\z|[+-]\d{2}:?\d{2}\z/)
+          Time.iso8601(str)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end