xero-kiwi 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 775f2c27c6c923aa8ab8c2cbb525d83ab7add7c174315e555428ccd45e520836
-  data.tar.gz: 5d5572e18a023da88435a091636094eae2800442348eaf6e9c19c25b1127e1fd
+  metadata.gz: 4deb1de10e85de555f19546d2d2243135b2f95fff462e45a2cac72e8622a9e31
+  data.tar.gz: 46dfc6f3e6eeeda92546e95b3161aea9802fb401e823d0f2ca67d91bab3555d7
 SHA512:
-  metadata.gz: f2f8890ad95b9c4c037a4a7d7470b3b32581730960552f6a21c436f3a9209bbf5af3a9ee78467c230c805d5d86de129f4510021098cc4dc2b2c5100e8bc2862c
-  data.tar.gz: 7fd1302cfac5d9e5b2e5a3b0c15a720d9ad08b02d550a65c70e4fb900fa7461ad7be9d3d37c4325aa2d6b2072ac35a6ef5a21b003b63e2cf2561ddf3f4df1e8f
+  metadata.gz: 781f5c1cfde039f7746984185d218d2fa9e07ceb66cb660d7227291f7e45210f97f590a97cb0d24dfa7c265843c98a37b3d4fd857b41d6cd6ab7e53d1db8d646
+  data.tar.gz: 727152993b2424d6513c44947db8b75cd4b1a8734b000e390644c59154ba72804cd48cf16b36e0df299df250b1b6a5eebeace82aba0319adc924a30125f5bdc6

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-17
+
+### Changed
+
+- Internal refactor of the accounting resource classes. Each resource now declares its fields through a shared `attribute` DSL (`lib/xero_kiwi/accounting/resource.rb`) rather than an `ATTRIBUTES` constant + hand-written `initialize`. Hydration logic (including the `/Date(ms)/` and ISO 8601 parsing previously duplicated across nine files) lives in a single `XeroKiwi::Accounting::Hydrator` module. The mixin also provides default `==` / `eql?` / `hash` (via an `identity :xxx_id` declaration for resources with a server-side primary key, structural `to_h`-based otherwise) and an ActiveRecord-style `inspect` that shows every attribute inline — nested objects collapse to a one-line reference and collections to a `[N items]` summary. No public API changes — constructor signatures and return types are preserved.
+
 ## [0.2.0] - 2026-04-15
 
 ### Added

data/Rakefile

@@ -57,7 +57,7 @@ def append_file_block(out, path)
   out << "\n" << separator << "\n"
   out << "FILE: #{path}\n"
   out << separator << "\n\n"
-  out << File.read(path) << "\n"
+  out << File.read(path, encoding: "UTF-8") << "\n"
 end
 
 namespace :llms do

data/docs/plans/attribute-dsl-refactor.md

@@ -0,0 +1,301 @@
+# Attribute DSL Refactor
+
+## Context
+
+Every accounting resource class in kiwi repeats the same pattern: an
+`ATTRIBUTES` name-map constant, an `attr_reader(*ATTRIBUTES.keys)` call, and a
+hand-written `initialize` that duplicates hydration logic across nine files.
+`parse_time` alone is copy-pasted into every resource. Nested-object and
+collection hydration (`Contact.new(attrs, reference: true)`,
+`(attrs["LineItems"] || []).map { … }`) follows an identical shape in every
+class but is written by hand each time.
+
+This is cheap today but will bite us soon. The upcoming query work
+(filtering/sorting/pagination) needs field-type metadata per attribute — adding
+a second `FIELDS` constant next to `ATTRIBUTES` would double the duplication.
+Writer support down the line will need serialisation metadata too. Both extend
+cleanly from a single attribute declaration.
+
+This plan extracts a small `attribute` DSL and migrates every accounting
+resource to it. No behaviour change, no public API change — constructors keep
+the same signature, existing specs keep passing. It's pure preparation for the
+0.3.0 querying work (tracked separately) and for writer support later.
+
+## Decisions locked in
+
+- **Reader-only.** No serialisation/writer concerns in this refactor. DSL
+  naming (`attribute`, not `reader` or `field`) leaves room for it later.
+- **No query metadata yet.** The `query: true` flag and `query_fields` map
+  come with the querying plan — not now. One concern at a time.
+- **Public API unchanged.** `Invoice.new(hash, reference: …)` keeps working
+  identically. `to_h`, `attr_reader`s, `==`, `hash`, `inspect`, resource-specific
+  helper methods (`accounts_receivable?`, etc.) all stay.
+- **Every accounting class migrates** — including nested value types
+  (`Address`, `Phone`, `LineItem`, `ContactPerson`, `ExternalLink`,
+  `PaymentTerm`, any others). Partial migration would leave two patterns
+  coexisting, which is worse than either alone.
+- **Version: flagged, not decided.** Internal refactor with no public API
+  change — defensibly a patch (`0.2.1`). Could also bundle under `0.3.0` since
+  that's the version the querying work will ship under and this is its
+  foundation. Confirm before bumping.
+
+## Design
+
+### 1. `XeroKiwi::Accounting::Resource` mixin
+
+```ruby
+# lib/xero_kiwi/accounting/resource.rb
+module XeroKiwi
+  module Accounting
+    module Resource
+      def self.included(base) = base.extend(ClassMethods)
+
+      module ClassMethods
+        def payload_key(key) = @payload_key = key
+
+        def attribute(name, xero:, type: :string, of: nil, hydrate: nil)
+          attributes[name] = { xero: xero, type: type, of: of, hydrate: hydrate }
+          attr_reader name
+        end
+
+        def attributes = (@attributes ||= {})
+
+        def from_response(payload)
+          return [] if payload.nil?
+
+          items = payload[@payload_key]
+          return [] if items.nil?
+
+          items.map { |attrs| new(attrs) }
+        end
+      end
+
+      def initialize(attrs, reference: false)
+        attrs         = attrs.transform_keys(&:to_s)
+        @is_reference = reference
+
+        self.class.attributes.each do |name, spec|
+          value = Hydrator.call(attrs[spec[:xero]], spec)
+          instance_variable_set("@#{name}", value)
+        end
+      end
+
+      def reference? = @is_reference
+
+      def to_h
+        self.class.attributes.keys.to_h { |k| [k, public_send(k)] }
+      end
+    end
+  end
+end
+```
+
+### 2. `XeroKiwi::Accounting::Hydrator`
+
+Shared hydration dispatch and the single home for `parse_time`.
+
+```ruby
+# lib/xero_kiwi/accounting/hydrator.rb
+module XeroKiwi
+  module Accounting
+    module Hydrator
+      module_function
+
+      def call(raw, spec)
+        return spec[:hydrate].call(raw) if spec[:hydrate]
+        return [] if spec[:type] == :collection && raw.nil?
+        return nil if raw.nil?
+
+        case spec[:type]
+        when :string, :enum, :guid, :bool, :decimal
+          raw
+        when :date
+          parse_time(raw)
+        when :object
+          spec[:of].new(raw, reference: true)
+        when :collection
+          raw.map { |item| spec[:of].new(item) }
+        else
+          raise ArgumentError, "unknown attribute type: #{spec[:type]}"
+        end
+      end
+
+      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
+```
+
+### 3. Supported attribute types
+
+| Type          | Hydrates to                                     | Notes                                      |
+|---------------|-------------------------------------------------|--------------------------------------------|
+| `:string`     | value as-is                                     | default                                    |
+| `:enum`       | value as-is                                     | semantic marker for future validation      |
+| `:guid`       | value as-is                                     | semantic marker for future query typing    |
+| `:bool`       | value as-is                                     |                                            |
+| `:decimal`    | value as-is                                     | Xero returns these as numbers or strings   |
+| `:date`       | `Time` via `Hydrator.parse_time`                | handles `/Date(ms)/` and ISO8601           |
+| `:object`     | `spec[:of].new(raw, reference: true)`           | requires `of:`                             |
+| `:collection` | `raw.map { spec[:of].new(item) }`, `nil` → `[]` | requires `of:`                             |
+
+Escape hatch: `hydrate: ->(raw) { … }` for one-off fields the built-in types
+can't express. Runs before dispatch.
+
+### 4. Before / after (example)
+
+Invoice before — 40+ lines of `initialize`, `parse_time` method, `ATTRIBUTES`
+constant duplicated:
+
+```ruby
+ATTRIBUTES = { invoice_id: "InvoiceID", … }.freeze
+attr_reader(*ATTRIBUTES.keys)
+
+def initialize(attrs, reference: false)
+  attrs                = attrs.transform_keys(&:to_s)
+  @is_reference        = reference
+  @invoice_id          = attrs["InvoiceID"]
+  @invoice_number      = attrs["InvoiceNumber"]
+  @contact             = attrs["Contact"] ? Contact.new(attrs["Contact"], reference: true) : nil
+  @date                = parse_time(attrs["Date"])
+  @line_items          = (attrs["LineItems"] || []).map { |li| LineItem.new(li) }
+  # … 30 more lines …
+end
+
+private
+
+def parse_time(value)
+  # … 15 lines, duplicated in 9 files …
+end
+```
+
+After — one declaration per field, no `initialize`, no `parse_time`:
+
+```ruby
+include Accounting::Resource
+
+payload_key "Invoices"
+
+attribute :invoice_id,     xero: "InvoiceID",     type: :guid
+attribute :invoice_number, xero: "InvoiceNumber", type: :string
+attribute :contact,        xero: "Contact",       type: :object,     of: Contact
+attribute :date,           xero: "Date",          type: :date
+attribute :line_items,     xero: "LineItems",     type: :collection, of: LineItem
+# …
+
+def accounts_receivable? = type == "ACCREC"
+def accounts_payable?    = type == "ACCPAY"
+
+def ==(other) = other.is_a?(Invoice) && other.invoice_id == invoice_id
+alias eql? ==
+def hash = [self.class, invoice_id].hash
+```
+
+### 5. Edge cases to preserve
+
+- **Raw pass-through fields** that are currently kept as plain hashes/arrays
+  (e.g. `Invoice#invoice_addresses`, `Contact#bank_account_details`) — use
+  `type: :string` (misnomer but harmless) or the `hydrate:` escape hatch with
+  an identity lambda. Audit each during migration.
+- **`reference: true` semantics** — nested `:object` attributes always hydrate
+  with `reference: true`; nested `:collection` attributes hydrate without it
+  (full objects). This matches today's behaviour per-file. If any class
+  currently deviates, that deviation gets a `hydrate:` escape hatch.
+- **Resource-specific helpers** (`accounts_receivable?`, `reference?`,
+  `inspect`, `==`, `hash`) stay inline on each class.
+- **Classes without list endpoints** (nested value types — `Address`, `Phone`,
+  etc.) use the DSL but don't call `payload_key`. `from_response` on them isn't
+  called; the method existing but unused is harmless.
+
+## Files
+
+### Create
+
+- `lib/xero_kiwi/accounting/resource.rb` — the DSL mixin.
+- `lib/xero_kiwi/accounting/hydrator.rb` — shared hydration + `parse_time`.
+- `spec/xero_kiwi/accounting/resource_spec.rb` — DSL unit tests.
+- `spec/xero_kiwi/accounting/hydrator_spec.rb` — hydrator unit tests.
+
+### Modify
+
+- `lib/xero_kiwi.rb` — `require` the new files before any accounting class.
+- Every `lib/xero_kiwi/accounting/*.rb` — migrate to `attribute` DSL, drop
+  `ATTRIBUTES`, drop hand-written `initialize`, drop private `parse_time`.
+  Concrete list: `contact.rb`, `contact_group.rb`, `contact_person.rb`,
+  `invoice.rb`, `credit_note.rb`, `prepayment.rb`, `overpayment.rb`,
+  `payment.rb`, `user.rb`, `branding_theme.rb`, `organisation.rb`, `address.rb`,
+  `phone.rb`, `external_link.rb`, `payment_term.rb`, `line_item.rb`, and any
+  other value classes in `lib/xero_kiwi/accounting/`.
+- `lib/xero_kiwi/version.rb` — bump (0.2.1 or 0.3.0 — confirm).
+- `CHANGELOG.md` — **Changed** entry describing the internal refactor.
+- `Gemfile.lock` — rebuild after version bump.
+
+## Testing strategy
+
+- **Hydrator unit specs:** each type dispatches correctly. `/Date(ms)/` parses.
+  ISO8601 with and without timezone parses. Empty/invalid strings return
+  `nil`. `:object` hydrates nested reference. `:collection` with `nil` →
+  `[]`, populated → `map`ped. `:collection` with `nil` + `hydrate:` runs the
+  lambda. Unknown type raises.
+- **Resource unit specs:** declare a throwaway class inside the spec with a
+  couple of attributes of each type, hydrate a fixture hash, assert every
+  reader returns the expected value, `to_h` returns a keyed hash, `payload_key`
+  + `from_response` parse an envelope.
+- **Existing accounting resource specs carry the real load.** They already
+  call `Class.new(fixture_hash)` and assert every reader — they should pass
+  unchanged. A regression in the DSL surfaces as real-resource spec failures,
+  which is exactly what we want.
+- **Client integration specs** — untouched, must still pass green.
+
+## Verification
+
+```sh
+bundle install
+bundle exec rspec                              # full suite green
+bundle exec rspec spec/xero_kiwi/accounting    # DSL + hydrator + every resource
+bundle exec rspec spec/xero_kiwi/client_spec.rb # list methods unaffected
+bundle exec rubocop                            # style still clean
+```
+
+Smoke check in IRB against a recorded fixture or live tenant:
+
+```ruby
+require "xero_kiwi"
+
+client = XeroKiwi::Client.new(access_token: ENV.fetch("XERO_TOKEN"))
+invoices = client.invoices(tenant)
+inv = invoices.first
+
+inv.invoice_id            # string
+inv.date                  # Time
+inv.contact               # Accounting::Contact, reference? == true
+inv.line_items            # Array<Accounting::LineItem>
+inv.to_h.keys             # every attribute name
+```
+
+## Follow-up
+
+Once this lands, the 0.3.0 querying plan picks up by:
+
+1. Adding a `query: true` option to `attribute`.
+2. Auto-populating `query_fields` on the class from attributes flagged
+   queryable.
+3. Building `Query::Filter` / `Query::Order` compilers against that map.
+4. Adding the `Page` return type, `each_*` helpers, and `modified_since`
+   support on the client.
+
+None of which requires re-touching the resource files.

data/lib/xero_kiwi/accounting/address.rb

@@ -6,53 +6,22 @@ module XeroKiwi
     #
     # See: https://developer.xero.com/documentation/api/accounting/types#addresses
     class Address
-      ATTRIBUTES = {
-        address_type:   "AddressType",
-        address_line_1: "AddressLine1",
-        address_line_2: "AddressLine2",
-        address_line_3: "AddressLine3",
-        address_line_4: "AddressLine4",
-        city:           "City",
-        region:         "Region",
-        postal_code:    "PostalCode",
-        country:        "Country",
-        attention_to:   "AttentionTo"
-      }.freeze
-
-      attr_reader(*ATTRIBUTES.keys)
-
-      def initialize(attrs)
-        attrs           = attrs.transform_keys(&:to_s)
-        @address_type   = attrs["AddressType"]
-        @address_line_1 = attrs["AddressLine1"]
-        @address_line_2 = attrs["AddressLine2"]
-        @address_line_3 = attrs["AddressLine3"]
-        @address_line_4 = attrs["AddressLine4"]
-        @city           = attrs["City"]
-        @region         = attrs["Region"]
-        @postal_code    = attrs["PostalCode"]
-        @country        = attrs["Country"]
-        @attention_to   = attrs["AttentionTo"]
-      end
+      include Resource
+
+      attribute :address_type,   xero: "AddressType"
+      attribute :address_line_1, xero: "AddressLine1"
+      attribute :address_line_2, xero: "AddressLine2"
+      attribute :address_line_3, xero: "AddressLine3"
+      attribute :address_line_4, xero: "AddressLine4"
+      attribute :city,           xero: "City"
+      attribute :region,         xero: "Region"
+      attribute :postal_code,    xero: "PostalCode"
+      attribute :country,        xero: "Country"
+      attribute :attention_to,   xero: "AttentionTo"
 
       def street?   = address_type == "STREET"
       def pobox?    = address_type == "POBOX"
       def delivery? = address_type == "DELIVERY"
-
-      def to_h
-        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
-      end
-
-      def ==(other)
-        other.is_a?(Address) && to_h == other.to_h
-      end
-      alias eql? ==
-
-      def hash = to_h.hash
-
-      def inspect
-        "#<#{self.class} type=#{address_type.inspect} city=#{city.inspect} country=#{country.inspect}>"
-      end
     end
   end
 end

data/lib/xero_kiwi/accounting/allocation.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "time"
-
 module XeroKiwi
   module Accounting
     # Represents an allocation of a credit note, prepayment, or overpayment
@@ -9,58 +7,15 @@ module XeroKiwi
     #
     # See: https://developer.xero.com/documentation/api/accounting/overpayments
     class Allocation
-      ATTRIBUTES = {
-        allocation_id: "AllocationID",
-        amount:        "Amount",
-        date:          "Date",
-        invoice:       "Invoice",
-        is_deleted:    "IsDeleted"
-      }.freeze
-
-      attr_reader(*ATTRIBUTES.keys)
-
-      def initialize(attrs)
-        attrs          = attrs.transform_keys(&:to_s)
-        @allocation_id = attrs["AllocationID"]
-        @amount        = attrs["Amount"]
-        @date          = parse_time(attrs["Date"])
-        @invoice       = attrs["Invoice"] ? Invoice.new(attrs["Invoice"], reference: true) : nil
-        @is_deleted    = attrs["IsDeleted"]
-      end
-
-      def to_h
-        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
-      end
-
-      def ==(other)
-        other.is_a?(Allocation) && other.allocation_id == allocation_id
-      end
-      alias eql? ==
-
-      def hash = [self.class, allocation_id].hash
-
-      def inspect
-        "#<#{self.class} allocation_id=#{allocation_id.inspect} " \
-          "amount=#{amount.inspect}>"
-      end
-
-      private
-
-      def parse_time(value)
-        return nil if value.nil?
+      include Resource
 
-        str = value.to_s.strip
-        return nil if str.empty?
+      identity :allocation_id
 
-        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
+      attribute :allocation_id, xero: "AllocationID", type: :guid
+      attribute :amount,        xero: "Amount",       type: :decimal
+      attribute :date,          xero: "Date",         type: :date
+      attribute :invoice,       xero: "Invoice",      type: :object, of: Invoice, reference: true
+      attribute :is_deleted,    xero: "IsDeleted",    type: :bool
     end
   end
 end

data/lib/xero_kiwi/accounting/branding_theme.rb

@@ -1,76 +1,22 @@
 # 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?
+      include Resource
 
-        str = value.to_s.strip
-        return nil if str.empty?
+      payload_key "BrandingThemes"
+      identity    :branding_theme_id
 
-        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
+      attribute :branding_theme_id, xero: "BrandingThemeID", type: :guid
+      attribute :name,              xero: "Name"
+      attribute :logo_url,          xero: "LogoUrl"
+      attribute :type,              xero: "Type"
+      attribute :sort_order,        xero: "SortOrder"
+      attribute :created_date_utc,  xero: "CreatedDateUTC", type: :date
     end
   end
 end