xero-kiwi 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f6a32ee3719881fa7bd110e3bd1abb532e76dfdcddeb93e580199deacf1fe35
-  data.tar.gz: 3b7ea0828116a3f20ce4557d17f85540859d977db14e1db40cd7113321ecaaa8
+  metadata.gz: 4deb1de10e85de555f19546d2d2243135b2f95fff462e45a2cac72e8622a9e31
+  data.tar.gz: 46dfc6f3e6eeeda92546e95b3161aea9802fb401e823d0f2ca67d91bab3555d7
 SHA512:
-  metadata.gz: 7182cd4adc572b4fe80ac9a43a3ed5f7075404d5eb3c25ae26e843f3a9b600d6891e5feaafcac202b0cd57258b20b63e72d318766080cf3b42a65c74b055c9d8
-  data.tar.gz: fb570096febd7f79e7d5643c87a81b7d5839156d576a430a267b1ca44b35fa0ab5c37723e63b8470b679e30bb88a5264c5134ca91b4caea072b7cb05c4372cd5
+  metadata.gz: 781f5c1cfde039f7746984185d218d2fa9e07ceb66cb660d7227291f7e45210f97f590a97cb0d24dfa7c265843c98a37b3d4fd857b41d6cd6ab7e53d1db8d646
+  data.tar.gz: 727152993b2424d6513c44947db8b75cd4b1a8734b000e390644c59154ba72804cd48cf16b36e0df299df250b1b6a5eebeace82aba0319adc924a30125f5bdc6

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [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
+
+- Optional proactive rate-limit throttling via a Redis-backed token bucket, keyed per tenant. Pass `throttle:` to `XeroKiwi::Client.new` to coordinate rate limits across processes (e.g. multiple Sidekiq workers hitting the same Xero tenant). Supports per-minute and per-day limits; per-minute waits are bounded by `max_wait`, per-day exhaustion raises `XeroKiwi::Throttle::DailyLimitExhausted`. Composes with the existing reactive retry layer — neither replaces the other. See `docs/throttling.md`.
+
+### Changed
+
+- `redis` is now a runtime dependency (used only if you opt into throttling).
+
 ## [0.1.1] - 2026-04-15
 
 - Add `lib/xero-kiwi.rb` shim so `gem "xero-kiwi"` in a Gemfile auto-requires the gem without needing `require: "xero_kiwi"`.

data/README.md

@@ -1,6 +1,6 @@
 # Xero Kiwi
 
-A Ruby wrapper for the [Xero](https://www.xero.com) Accounting API. XeroKiwi handles
+A Ruby wrapper for the [Xero](https://www.xero.com) Accounting API. Xero Kiwi handles
 the unglamorous parts of integrating with Xero — OAuth2, token refresh, rate
 limiting, retries — so the rest of your code can focus on the actual business
 problem.
@@ -33,7 +33,7 @@ gem "xero-kiwi"
 
 Then run `bundle install`.
 
-XeroKiwi requires Ruby 3.4.1 or newer.
+Xero Kiwi requires Ruby 3.4.1 or newer.
 
 ## Quick start
 
@@ -70,14 +70,36 @@ below.
 | [Tokens](docs/tokens.md) | The `XeroKiwi::Token` value object, automatic refresh, revocation, persistence callbacks |
 | [OAuth](docs/oauth.md) | Authorization URL building, code exchange, PKCE, ID token verification, full Rails-style example |
 | [Errors](docs/errors.md) | The error hierarchy, what to catch and when |
-| [Retries and rate limits](docs/retries-and-rate-limits.md) | How XeroKiwi handles 429s and transient failures, customising the retry policy |
+| [Retries and rate limits](docs/retries-and-rate-limits.md) | How Xero Kiwi handles 429s and transient failures, customising the retry policy |
+| [Throttling](docs/throttling.md) | Redis-backed token bucket for proactive rate-limit coordination across multiple workers |
 
 ## Status
 
-XeroKiwi is in early development. The API surface for the features documented above
+Xero Kiwi is in early development. The API surface for the features documented above
 is stable, but expect new resource methods to be added over time. Breaking
 changes will be called out in the [changelog](CHANGELOG.md).
 
+## Development
+
+The gem runs natively via Bundler — nothing is containerised for everyday
+development. A `docker-compose.yml` exists for *external services* the specs
+need, currently just Redis (used by the throttle limiter's Lua-backed specs).
+
+```sh
+bundle install
+docker compose up -d redis   # optional; only needed for :redis-tagged specs
+bundle exec rspec
+```
+
+Without Redis running, specs tagged `:redis` are filtered out automatically
+(see [spec/spec_helper.rb](spec/spec_helper.rb)) so the suite still passes.
+Override the test Redis URL with `TEST_REDIS_URL=...` if you don't want the
+default `redis://127.0.0.1:6379/15`.
+
+```sh
+docker compose down          # when you're done
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/Rakefile

@@ -44,8 +44,8 @@ LLMS_FULL_PATH = "llms-full.txt"
 # expected output.
 def build_llms_full
   out = +""
-  out << "# XeroKiwi — full documentation\n\n"
-  out << "This file is the complete documentation for the XeroKiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
+  out << "# Xero Kiwi — full documentation\n\n"
+  out << "This file is the complete documentation for the Xero Kiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
   out << "For the curated index version, see llms.txt in the same directory.\n\n"
   out << "Source: https://github.com/douglasgreyling/xero-kiwi\n\n"
   LLMS_SOURCE_FILES.each { |path| append_file_block(out, path) }
@@ -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/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: xero-kiwi-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 2s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:

data/docs/accounting/branding-theme.md

@@ -58,7 +58,7 @@ sets.
 ## Date parsing
 
 The `created_date_utc` field uses Xero's .NET JSON timestamp format
-(`/Date(946684800000+0000)/`). XeroKiwi parses both .NET JSON and ISO 8601
+(`/Date(946684800000+0000)/`). Xero Kiwi parses both .NET JSON and ISO 8601
 formats transparently — the attribute is always a UTC `Time` object.
 
 ## Error behaviour

data/docs/accounting/organisation.md

@@ -82,7 +82,7 @@ API. Connections use ISO 8601 strings (e.g. `"2019-07-09T23:40:30.1833130"`),
 but the Accounting API (including Organisation) uses the legacy .NET JSON
 format: `/Date(1574275974000)/`.
 
-XeroKiwi handles both transparently — all `Time` attributes are parsed to UTC
+Xero Kiwi handles both transparently — all `Time` attributes are parsed to UTC
 `Time` objects regardless of which format Xero sends. You don't need to think
 about this unless you're looking at raw cassette data or debugging timestamp
 issues.

data/docs/accounting/user.md

@@ -74,7 +74,7 @@ Two users are `==` if they share the same `user_id`. `#hash` is consistent with
 ## Date parsing
 
 The `updated_date_utc` field uses Xero's .NET JSON timestamp format
-(`/Date(1516230549137+0000)/`). XeroKiwi parses both .NET JSON and ISO 8601
+(`/Date(1516230549137+0000)/`). Xero Kiwi parses both .NET JSON and ISO 8601
 formats transparently — the attribute is always a UTC `Time` object.
 
 ## Error behaviour

data/docs/client.md

@@ -3,7 +3,7 @@
 `XeroKiwi::Client` is the entry point for talking to Xero's accounting API. You
 construct one with credentials and call resource methods on it. The client
 holds the OAuth token state, knows how to refresh it, and translates HTTP
-errors into XeroKiwi exceptions.
+errors into Xero Kiwi exceptions.
 
 ## Constructing a client
 
@@ -97,7 +97,7 @@ skipped: a 401 raises immediately and you handle it in your own code.
 
 ## Custom adapters
 
-XeroKiwi uses Faraday under the hood, so you can swap the HTTP adapter for
+Xero Kiwi uses Faraday under the hood, so you can swap the HTTP adapter for
 testing or for connection pooling:
 
 ```ruby
@@ -123,7 +123,7 @@ test adapter swallows refresh requests too.
 
 ## Customising the retry policy
 
-`retry_options:` is merged into XeroKiwi's defaults, so you only need to specify
+`retry_options:` is merged into Xero Kiwi's defaults, so you only need to specify
 overrides:
 
 ```ruby

data/docs/connections.md

@@ -74,7 +74,7 @@ old_connections - new_connections # diff by id
 
 Xero serialises dates in C# DateTime format and frequently omits the timezone
 marker on values that are documented as UTC (e.g. `"2019-07-09T23:40:30.1833130"`).
-XeroKiwi force-appends a `Z` before parsing so you always get a UTC `Time` back —
+Xero Kiwi force-appends a `Z` before parsing so you always get a UTC `Time` back —
 without this, `Time.parse` would silently fall back to local time and you'd
 get the wrong instant.
 

data/docs/errors.md

@@ -1,6 +1,6 @@
 # Errors
 
-Every failure path in XeroKiwi raises a typed exception. This page walks through
+Every failure path in Xero Kiwi raises a typed exception. This page walks through
 the hierarchy, explains what each class means, and tells you what to catch
 in common situations.
 
@@ -8,7 +8,7 @@ in common situations.
 
 ```
 StandardError
-└─ XeroKiwi::Error                       (root — catch this for "anything XeroKiwi raised")
+└─ XeroKiwi::Error                       (root — catch this for "anything Xero Kiwi raised")
    ├─ XeroKiwi::APIError                 (root for HTTP responses; carries status + body)
    │  ├─ XeroKiwi::AuthenticationError   (401)
    │  │  ├─ XeroKiwi::TokenRefreshError  (refresh round-trip failed)
@@ -22,7 +22,7 @@ StandardError
 
 A few things worth noticing about the shape:
 
-- **Everything XeroKiwi raises** descends from `XeroKiwi::Error`. If you only want
+- **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
   one rescue clause for "the Xero integration broke," catch this.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
@@ -38,7 +38,7 @@ A few things worth noticing about the shape:
 ### `XeroKiwi::Error`
 
 The root class. Inherits from `StandardError`. You almost never raise this
-directly — it exists as a catch-all for code that wants to rescue "any XeroKiwi
+directly — it exists as a catch-all for code that wants to rescue "any Xero Kiwi
 problem" without enumerating every subclass.
 
 ### `XeroKiwi::APIError`
@@ -62,7 +62,7 @@ The access token was rejected. The most common causes:
 - Token has the wrong scopes for this endpoint.
 - The wrong tenant ID was passed in the `Xero-Tenant-Id` header.
 
-If your client has refresh capability, XeroKiwi will already have tried to
+If your client has refresh capability, Xero Kiwi will already have tried to
 refresh and retry exactly once before this raises. Seeing `AuthenticationError`
 on a refresh-capable client means **the second 401 also failed** — refresh
 won't fix it, and you need to either re-authorise or surface the error.
@@ -115,9 +115,9 @@ Inspect `error.body` to surface it.
 
 ### `XeroKiwi::ServerError` (HTTP 5xx)
 
-A 5xx response that wasn't retried. XeroKiwi retries 502/503/504 automatically
+A 5xx response that wasn't retried. Xero Kiwi retries 502/503/504 automatically
 (see [retries and rate limits](retries-and-rate-limits.md)) so by the time
-you see this, the retries are exhausted or the status was 500 (which XeroKiwi
+you see this, the retries are exhausted or the status was 500 (which Xero Kiwi
 deliberately doesn't retry, since 500s are usually persistent bugs in the
 request rather than transient infrastructure issues).
 
@@ -164,7 +164,7 @@ The error message has a brief description of which check failed (e.g.
 
 ## What to catch when
 
-### "Any XeroKiwi failure"
+### "Any Xero Kiwi failure"
 
 ```ruby
 begin
@@ -256,12 +256,12 @@ Order matters — `TokenRefreshError` is more specific than
 
 ## Things the error system deliberately does NOT do
 
-- **No "this error is retryable" predicate.** XeroKiwi already retries the
+- **No "this error is retryable" predicate.** Xero Kiwi already retries the
   cases that *should* be retried at the HTTP level. By the time an exception
   reaches your code, the retries are exhausted and the situation is
   application-level. Adding `error.retryable?` would create a tempting
   foot-gun where callers retry inside their own code, doubling up on the
-  retries XeroKiwi is already doing.
+  retries Xero Kiwi is already doing.
 - **No automatic Sentry / Bugsnag integration.** Errors raise normally;
   configure your own observability layer to catch them at the boundary.
 - **No `error.code` enum.** The HTTP `status` is the enum. Inspecting it

data/docs/getting-started.md

@@ -16,7 +16,7 @@ Before you can talk to Xero from Ruby, you need:
 
 ## Installing the gem
 
-Add XeroKiwi to your `Gemfile`:
+Add Xero Kiwi to your `Gemfile`:
 
 ```ruby
 gem "xero-kiwi"
@@ -30,7 +30,7 @@ bundle install
 
 ## The mental model
 
-XeroKiwi is built around a small set of objects, each with one job:
+Xero Kiwi is built around a small set of objects, each with one job:
 
 | Object | What it does |
 |--------|--------------|

data/docs/oauth.md

@@ -198,7 +198,7 @@ token = oauth.exchange_code(
 
 If you pass a `pkce:` to `authorization_url` but **forget** the
 `code_verifier:` on `exchange_code`, Xero will reject the exchange with
-`invalid_grant` and XeroKiwi will raise `XeroKiwi::OAuth::CodeExchangeError`.
+`invalid_grant` and Xero Kiwi will raise `XeroKiwi::OAuth::CodeExchangeError`.
 
 ## Step 2: handling the callback
 
@@ -489,7 +489,7 @@ end
 
 ## Things OAuth deliberately does NOT do
 
-- **No session storage.** XeroKiwi gives you `generate_state` and
+- **No session storage.** Xero Kiwi gives you `generate_state` and
   `generate_pkce` as helpers but never touches your session/cookies/Redis.
   Where you stash the values is your problem — and that's a feature,
   because every framework is different.

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.