intacct-rest 1.0.0

data/lib/intacct_rest/model/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # Shared by any IntacctRest::Model class: a small `validate` macro plus
+    # #errors/#valid?. Not tied to Vendor specifically — Customer, Bill,
+    # etc. can reuse this the same way.
+    #
+    #   class Thing < IntacctRest::Model::Base
+    #     attr_accessor :name
+    #     validate :presence, [:name]
+    #   end
+    class Base
+      class << self
+        # kind: a key registered in IntacctRest::Validators (:presence,
+        # :kind_of, :inclusion, ...). Trailing positional args before the
+        # final Array of attribute names are passed through to that
+        # validator (e.g. the type symbol for :kind_of, the list for
+        # :inclusion).
+        #
+        # on: an optional operation context (:create, :update, ...). A
+        # validation declared with on: only runs when #errors/#valid? is
+        # called with that same context; without on: it always runs.
+        def validate(kind, *args, on: nil)
+          attributes = Array(args.pop)
+          validators << { kind: kind, attributes: attributes, options: args, on: on }
+        end
+
+        def validators
+          @validators ||= superclass.respond_to?(:validators) ? superclass.validators.dup : []
+        end
+      end
+
+      def errors(context = nil)
+        self.class.validators.flat_map do |spec|
+          next [] unless spec[:on].nil? || spec[:on] == context
+
+          validator = IntacctRest::Validators.fetch(spec[:kind])
+          spec[:attributes].flat_map { |attribute| validator.call(self, attribute, *spec[:options]) }
+        end
+      end
+
+      def valid?(context = nil)
+        errors(context).empty?
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/bill.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # An AP bill's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateBill) is what actually sends it.
+    #
+    # Nested objects (vendor, term, currency, lines, ...) are NOT
+    # individually modeled — pass them as raw Hashes using Intacct's
+    # native (camelCase) nested key names, e.g.:
+    #
+    #   vendor: { "id" => "1099 Int" }
+    #   lines: [{ "txnAmount" => "5", "glAccount" => { "id" => "6000" } }]
+    #
+    # Nested required fields (vendor.id, currency.txnCurrency,
+    # lines[].txnAmount/glAccount, lines[].dimensions.location, ...) are
+    # not validated client-side — only top-level presence/type is.
+    # Intacct's own 400 response is the source of truth for those, same
+    # boundary already accepted for Invoice/Customer/Vendor's nested
+    # objects.
+    class Bill < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-payable/bill'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_BILL_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post after a successful create — writable here
+      # even though Intacct itself treats them as read-only.
+      READONLY_ATTRIBUTES = %i[
+        key id href module_name record_type due_in_days total_base_amount total_base_amount_due
+        total_txn_amount total_txn_amount_due is_system_generated purchasing_document
+        recurring_schedule e_invoice_status import_status import_error_message recipient_email
+        sender_email anomaly_code document_source source_module payment_information retainage
+        customer_refund entity web_url audit
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[due_date created_date]
+
+      validate :kind_of, :string, %i[
+        bill_number state reference_number description posting_date discount_cut_off_date
+        due_date recommended_payment_date created_date invoice_type invoice_mode
+      ]
+      validate :kind_of, :boolean, %i[is_on_hold is_tax_inclusive]
+      validate :kind_of, :hash, %i[
+        vendor term contacts currency tax_solution bill_summary bill_back_template attachment
+        dispute refuse
+      ]
+      validate :kind_of, :array, %i[lines]
+
+      # source: an arbitrary domain object (ActiveRecord record, OpenStruct,
+      # another Model::Bill, ...) to pull matching attributes off of via
+      # duck-typing — any WRITABLE_ATTRIBUTES/READONLY_ATTRIBUTES key it
+      # responds to is copied over. Explicit keyword attributes always win
+      # over whatever the source provided.
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      # Ruby-side attributes (unmapped, no custom fields) — useful for
+      # logging/introspection without the camelCase JSON translation.
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/bill_line.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # An AP bill line's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateBillLine) is what actually sends
+    # it.
+    #
+    # This is a standalone-creatable object (POST
+    # /objects/accounts-payable/bill-line) distinct from the raw line-item
+    # Hashes accepted by Model::Bill#lines — Intacct allows both: send
+    # lines inline with the bill, or create them separately against an
+    # existing bill via `bill: { "key" => "..." }`.
+    #
+    # Nested objects (glAccount, dimensions, allocation, ...) are NOT
+    # individually modeled — pass them as raw Hashes using Intacct's
+    # native (camelCase) nested key names.
+    class BillLine < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-payable/bill-line'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_BILL_LINE_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post after a successful create — writable here
+      # even though Intacct itself treats them as read-only.
+      READONLY_ATTRIBUTES = %i[
+        key id href line_number bill_amount base_amount currency payment_information
+        is_sub_total base_location retainage created_date audit
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[bill txn_amount gl_account]
+      validate :kind_of, :string, %i[txn_amount total_txn_amount memo has_form1099]
+      validate :kind_of, :boolean, %i[release_to_pay]
+      validate :kind_of, :hash, %i[
+        vendor gl_account override_offset_gl_account account_label allocation form1099 project
+        fixed_asset amortization_template purchasing dimensions bill
+      ]
+      validate :kind_of, :array, %i[tax_entries]
+
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/contact.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # A contact's data and validations only — no config, no token
+    # provider, no HTTP, and no create endpoint of its own (Intacct has no
+    # standalone "create a contact" endpoint documented; contacts are
+    # referenced by id from vendor/customer's `contacts`/`contact_list`
+    # fields, which stay raw Hashes there). This is a small typed helper
+    # for building that nested payload with validation.
+    class Contact < IntacctRest::Model::Base
+      ATTRIBUTES = IntacctRest::Configuration::DEFAULT_CONTACT_ATTRIBUTES
+
+      attr_accessor(*ATTRIBUTES.keys)
+
+      validate :presence, %i[id]
+      validate :kind_of, :string, %i[id international_tax_id]
+      validate :kind_of, :boolean, %i[show_in_contact_list]
+      validate :kind_of, :hash, %i[tax electronic_invoice_details electronic_address]
+
+      # source: an arbitrary domain object (ActiveRecord record, OpenStruct,
+      # another Model::Contact, ...) to pull matching attributes off of via
+      # duck-typing. Explicit keyword attributes always win over whatever
+      # the source provided.
+      def initialize(source = nil, **attributes)
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      # Ruby-side attributes (unmapped) — useful for logging/introspection
+      # without the camelCase JSON translation.
+      def attributes
+        ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end
+      end
+
+      private
+
+      def attributes_from(source)
+        ATTRIBUTES.keys.each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/currency.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # Currency details nested inside an invoice header or invoice line
+    # (baseCurrency/txnCurrency/exchangeRate). Intacct has no standalone
+    # "create a currency" endpoint anywhere in its REST API — this exists
+    # purely as a small, validated way to build that nested Hash, e.g.:
+    #
+    #   currency = IntacctRest::Model::Currency.new(txn_currency: "EUR")
+    #   invoice.currency = currency.payload
+    #
+    # exchangeRate stays a raw Hash — not individually modeled.
+    class Currency < IntacctRest::Model::Base
+      ATTRIBUTES = IntacctRest::Configuration::DEFAULT_CURRENCY_ATTRIBUTES
+
+      attr_accessor(*ATTRIBUTES.keys)
+
+      validate :kind_of, :string, %i[base_currency txn_currency]
+      validate :kind_of, :hash, %i[exchange_rate]
+
+      # source: an arbitrary domain object to pull matching attributes off
+      # of via duck-typing. Explicit keyword attributes always win.
+      def initialize(source = nil, **attributes)
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def attributes
+        ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      # The camelCase Hash to embed into a parent's payload.
+      def payload
+        ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end
+      end
+
+      private
+
+      def attributes_from(source)
+        ATTRIBUTES.keys.each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/customer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # A customer's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateCustomer) is what actually sends it.
+    #
+    # Nested objects (contacts, term, vendor, ...) are NOT individually
+    # modeled — pass them as raw Hashes using Intacct's native (camelCase)
+    # nested key names, e.g. term: { "id" => "Net 15" }. `vendor` is how a
+    # customer references an associated vendor record, same raw-Hash
+    # pattern: vendor: { "id" => "V-00014" }.
+    class Customer < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-receivable/customer'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_CUSTOMER_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post after a successful create — writable here
+      # even though Intacct itself treats them as read-only, since this is
+      # the only place that result gets recorded.
+      READONLY_ATTRIBUTES = %i[
+        key href total_due last_invoice_created_date last_statement_generated_date
+        subscription_end_date entity web_url audit
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[name]
+
+      validate :kind_of, :string, %i[
+        id name status tax_id discount_percent advance_bill_by advance_bill_by_type
+        customer_resale_number delivery_options override_price_list currency notes
+        customer_restriction
+      ]
+      validate :kind_of, :boolean, %i[is_on_hold email_opt_in is_one_time_use disable_refund]
+      validate :kind_of, :numeric, %i[credit_limit retainage_percentage]
+      validate :kind_of, :hash, %i[
+        customer_type parent sales_representative default_revenue_gl_account shipping_method
+        contacts restrictions term customer_message territory vendor account_group
+        account_label attachment price_list price_schedule override_offset_gl_account
+        customer_account_health
+      ]
+      validate :kind_of, :array, %i[
+        contact_list customer_email_templates restricted_locations restricted_departments
+      ]
+
+      # source: an arbitrary domain object (ActiveRecord record, OpenStruct,
+      # another Model::Customer, ...) to pull matching attributes off of via
+      # duck-typing — any WRITABLE_ATTRIBUTES/READONLY_ATTRIBUTES key it
+      # responds to is copied over. Explicit keyword attributes always win
+      # over whatever the source provided.
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      # Ruby-side attributes (unmapped, no custom fields) — useful for
+      # logging/introspection without the camelCase JSON translation.
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/invoice.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # An AR invoice's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateInvoice) is what actually sends it.
+    #
+    # Nested objects (customer, lines, currency, term, ...) are NOT
+    # individually modeled — pass them as raw Hashes using Intacct's
+    # native (camelCase) nested key names, e.g.:
+    #
+    #   customer: { "id" => "C-00019" }
+    #   lines: [{ "txnAmount" => "100.40", "glAccount" => { "id" => "5004" } }]
+    #
+    # Nested required fields (customer.id, lines[].txnAmount, ...) are not
+    # validated client-side — only top-level presence/type is. Intacct's
+    # own 400 response is the source of truth for those, same boundary
+    # already accepted for Vendor's nested objects.
+    class Invoice < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-receivable/invoice'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_INVOICE_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post after a successful create — writable here
+      # even though Intacct itself treats them as read-only, since this is
+      # the only place that result gets recorded. `href` is appended even
+      # though the invoice object schema omits it — the actual 201
+      # response includes it, same as every other object here.
+      READONLY_ATTRIBUTES = %i[
+        key id record_type module_key due_in_days sales_document discount_cut_off_date
+        total_base_amount total_base_amount_due total_txn_amount total_txn_amount_due
+        dunning_count recurring_schedule payment_information is_system_generated_document
+        e_invoice_status dispute refuse download_url allow_online_payment provider_payment
+        retainage project_contract project_contract_billing architect
+        project_contract_billing_invoice_summary entity web_url audit href
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[invoice_date due_date]
+
+      validate :kind_of, :string, %i[
+        invoice_number state reference_number description invoice_date due_date
+        invoice_type invoice_mode
+      ]
+      validate :kind_of, :hash, %i[
+        currency customer_message contacts billback_template attachment customer term
+        tax_solution invoice_summary
+      ]
+      validate :kind_of, :array, %i[lines]
+
+      # source: an arbitrary domain object (ActiveRecord record, OpenStruct,
+      # another Model::Invoice, ...) to pull matching attributes off of via
+      # duck-typing — any WRITABLE_ATTRIBUTES/READONLY_ATTRIBUTES key it
+      # responds to is copied over. Explicit keyword attributes always win
+      # over whatever the source provided.
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      # Ruby-side attributes (unmapped, no custom fields) — useful for
+      # logging/introspection without the camelCase JSON translation.
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end