xero-kiwi 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b980ba3e8f03590d2ca887887d8509268bf87df52b882eef4730a9ce1512250c
-  data.tar.gz: bdd4952e2b7d1fd3af201f2446d17d5cd7f2bfe86e58ee9002f4115cc5624240
+  metadata.gz: 9e67980bd7d7be1131ee07b55847cd4633a527eec4159103ba43551903f0870c
+  data.tar.gz: f06a30a5311f02be7d8695344a7f8eb65e76f4b0abab1743f23b9701f7655600
 SHA512:
-  metadata.gz: e7086fef7948e63b5d9437a164a241f819e5a96beead2eb2701989613e8b95f643d805be209a63b98ab3dcd278c7e81f46165de054f1fd865318abb82a13e0e9
-  data.tar.gz: 94c08345afefa1b130634ab9d643052d14a24ba5200ae60a7b324344706d71465e9cecb6ce30e183876dafdf7bde0fcdbbaea487869ea99073bb388f2a7f8ab2
+  metadata.gz: bf15925c5971526baeb6c3773de4f454ab917509200794b05957b27eabdfb4691e757a01f9defca50357cf0ce8ba7aa504b8e29973685c1428b365b28d80c5bf
+  data.tar.gz: 854a1cc894da5a8706e084f1b2e328a3529470f785e4cc22c27d80080ec7c2780cf3db40eb3f919fd9afd359539a879af82d241b6a2061f3673fa80ead876357

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-26
+
+### Documentation
+
+- Pinned down the scope of `Resource#raw`, which was ambiguous enough to mislead a real consumer. It holds the resource's own item hash — `contact.raw` has no `"Contacts"` key — and it is the JSON representation specifically. Xero's XML representation nests differently (no arrays, so one child parses to a Hash and several to an Array), so `raw` cannot reproduce an XML-derived shape. `docs/client.md` gains a short migration section covering what that means for anyone replacing a client that sent `Accept: text/xml` and has stored payloads. Specs added for both the envelope scope and the PascalCase/snake_case split. The migration section sorts readers into the two piles that behave differently: ones that dig the XML-only structure and must change, and ones that already normalise (`[value].flatten.compact`) where only the writer changes and stored rows stay readable.
+
 ## [0.5.0] - 2026-09-26
 
 The sync-support release: everything needed to drive a full-tenant sync through kiwi rather than around it.

data/docs/client.md

@@ -59,23 +59,81 @@ contact.raw
 # => {"ContactID" => "…", "ContactPersons" => [...], "SomeNewField" => "…"}
 ```
 
-Use it to reach fields kiwi doesn't model yet, or to store what Xero sent
-verbatim.
-
-Three things to know:
-
+Use it to reach fields kiwi doesn't model yet.
+
+Five things to know:
+
+- **It's the item, not the envelope.** `contact.raw` has no `"Contacts"`
+  key and `organisation.raw` has no `"Organisations"` key — kiwi unwraps
+  the envelope before building a resource, so there's nothing left of it by
+  the time `raw` is populated. If you need the envelope back, you're
+  rebuilding it yourself.
+- **It's the JSON representation.** Kiwi sends
+  `Accept: application/json`. Xero also serves XML, which nests
+  differently — XML has no arrays, so a single child parses to a Hash and
+  several to an Array, where JSON is always an Array. `raw` cannot
+  reproduce an XML-derived shape. See [migrating from an XML
+  client](#migrating-from-an-xml-based-client) below.
 - **`#raw` is not `#to_h`.** `to_h` is a snake_case projection rebuilt from
   the modelled attributes — different keys, different nesting. If you store
   `to_h` where you meant to store the payload, readers fail by returning
   nil rather than raising.
-- **It's top-level only.** Nested objects (line items, addresses, contact
-  persons) have no `#raw` of their own. They don't need one: the top-level
-  hash already holds every nested payload, so `contact.raw["ContactPersons"]`
-  gets there.
+- **It's per resource, not per nested object.** Line items, addresses and
+  contact persons have no `#raw` of their own. They don't need one: the
+  resource's hash already holds every nested payload, so
+  `contact.raw["ContactPersons"]` gets there.
 - **It costs memory.** Every resource holds its source hash alongside the
   hydrated attributes, which roughly doubles the footprint of a large page.
   That's why it's off by default.
 
+### Migrating from an XML-based client
+
+If you're replacing a Xero client that sent `Accept: text/xml` — HTTParty
+and similar default to it — any payloads you already have stored are
+XML-shaped, and `raw` will not match them. The differences are structural,
+not cosmetic:
+
+| | XML (`text/xml`) | JSON (`application/json`) |
+|---|---|---|
+| Organisation body | `{"Organisations" => {"Organisation" => {…}}}` | `{"Organisations" => [{…}]}` |
+| One address | `{"Address" => {…}}` | `[{…}]` |
+| Several addresses | `{"Address" => [{…}, {…}]}` | `[{…}, {…}]` |
+
+The single-child collapse is the one that catches people: under XML a
+contact with one person parses to a Hash and a contact with two parses to
+an Array, from the same endpoint. Code written against that has a
+normalising step somewhere, whether or not its author knew why.
+
+No client setting reproduces these shapes — they're artefacts of an XML
+parse kiwi doesn't do. But the remedy isn't the same everywhere, and it's
+worth sorting your readers into two piles before planning the work.
+
+**Readers that dig the XML-only structure have to change.** Something like
+`dig("Organisations", "Organisation", "Addresses", "Address")` returns nil
+against anything kiwi produces, whether you store `raw` or `to_h`.
+Promote the fields those readers need to real columns and use `raw` for
+the backfill — it's the true payload, so it carries everything required to
+populate them.
+
+**Readers that already normalise usually survive untouched.** A reader
+doing `[value].flatten.compact` handles the Hash case, the Array case and
+nil identically, so a JSON array flows straight through. If the keys it
+reads are the same in both representations, only the *writer* changes:
+stop unwrapping, store the array. Existing rows stay readable, and you
+skip a migration entirely.
+
+Type coercion is usually fine in that second pile too. XML gives you
+strings — `"false"` rather than `false` — and if the reader hands that to
+something like ActiveModel's boolean cast, both the old string and the new
+real boolean land on the same value.
+
+One piece of luck worth knowing about: the two piles tend to fail
+differently. A `dig` that misses returns nil and writes a blank record
+quietly. Code that assumed a Hash, such as `Array#to_h` on what is now a
+list, raises `TypeError` on the first record with data in it. The noisy
+failures are the ones you can trust to find themselves — budget your
+review time for the silent ones.
+
 ## What the client gives you
 
 | Method | Returns | Purpose |

data/lib/xero_kiwi/accounting/resource.rb

@@ -135,9 +135,20 @@ module XeroKiwi
         end
       end
 
-      # Xero's response hash for this resource, exactly as it arrived, or nil
-      # unless the client was built with `retain_raw: true`. Use it to reach
-      # fields the gem doesn't model, or to store the payload verbatim.
+      # This resource's own hash from Xero's JSON response, exactly as it
+      # arrived, or nil unless the client was built with `retain_raw: true`.
+      # Use it to reach fields the gem doesn't model.
+      #
+      # Scope is the item, NOT the enclosing envelope: `contact.raw` has no
+      # "Contacts" key, and `organisation.raw` no "Organisations" key. Kiwi
+      # unwraps the envelope before a resource is built, so there is nothing
+      # left of it by the time this is populated.
+      #
+      # It is also the JSON representation specifically. Kiwi sends
+      # `Accept: application/json`; Xero's XML representation nests
+      # differently — no arrays, so one child is a Hash and several are an
+      # Array — and `raw` cannot reproduce that shape. Worth knowing when
+      # migrating off an XML-based Xero client with stored payloads.
       #
       # Note `to_h` is NOT this — it's a snake_case projection rebuilt from
       # the modelled attributes, with different keys and different nesting.

data/lib/xero_kiwi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XeroKiwi
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/llms-full.txt

@@ -346,23 +346,81 @@ contact.raw
 # => {"ContactID" => "…", "ContactPersons" => [...], "SomeNewField" => "…"}
 ```
 
-Use it to reach fields kiwi doesn't model yet, or to store what Xero sent
-verbatim.
-
-Three things to know:
-
+Use it to reach fields kiwi doesn't model yet.
+
+Five things to know:
+
+- **It's the item, not the envelope.** `contact.raw` has no `"Contacts"`
+  key and `organisation.raw` has no `"Organisations"` key — kiwi unwraps
+  the envelope before building a resource, so there's nothing left of it by
+  the time `raw` is populated. If you need the envelope back, you're
+  rebuilding it yourself.
+- **It's the JSON representation.** Kiwi sends
+  `Accept: application/json`. Xero also serves XML, which nests
+  differently — XML has no arrays, so a single child parses to a Hash and
+  several to an Array, where JSON is always an Array. `raw` cannot
+  reproduce an XML-derived shape. See [migrating from an XML
+  client](#migrating-from-an-xml-based-client) below.
 - **`#raw` is not `#to_h`.** `to_h` is a snake_case projection rebuilt from
   the modelled attributes — different keys, different nesting. If you store
   `to_h` where you meant to store the payload, readers fail by returning
   nil rather than raising.
-- **It's top-level only.** Nested objects (line items, addresses, contact
-  persons) have no `#raw` of their own. They don't need one: the top-level
-  hash already holds every nested payload, so `contact.raw["ContactPersons"]`
-  gets there.
+- **It's per resource, not per nested object.** Line items, addresses and
+  contact persons have no `#raw` of their own. They don't need one: the
+  resource's hash already holds every nested payload, so
+  `contact.raw["ContactPersons"]` gets there.
 - **It costs memory.** Every resource holds its source hash alongside the
   hydrated attributes, which roughly doubles the footprint of a large page.
   That's why it's off by default.
 
+### Migrating from an XML-based client
+
+If you're replacing a Xero client that sent `Accept: text/xml` — HTTParty
+and similar default to it — any payloads you already have stored are
+XML-shaped, and `raw` will not match them. The differences are structural,
+not cosmetic:
+
+| | XML (`text/xml`) | JSON (`application/json`) |
+|---|---|---|
+| Organisation body | `{"Organisations" => {"Organisation" => {…}}}` | `{"Organisations" => [{…}]}` |
+| One address | `{"Address" => {…}}` | `[{…}]` |
+| Several addresses | `{"Address" => [{…}, {…}]}` | `[{…}, {…}]` |
+
+The single-child collapse is the one that catches people: under XML a
+contact with one person parses to a Hash and a contact with two parses to
+an Array, from the same endpoint. Code written against that has a
+normalising step somewhere, whether or not its author knew why.
+
+No client setting reproduces these shapes — they're artefacts of an XML
+parse kiwi doesn't do. But the remedy isn't the same everywhere, and it's
+worth sorting your readers into two piles before planning the work.
+
+**Readers that dig the XML-only structure have to change.** Something like
+`dig("Organisations", "Organisation", "Addresses", "Address")` returns nil
+against anything kiwi produces, whether you store `raw` or `to_h`.
+Promote the fields those readers need to real columns and use `raw` for
+the backfill — it's the true payload, so it carries everything required to
+populate them.
+
+**Readers that already normalise usually survive untouched.** A reader
+doing `[value].flatten.compact` handles the Hash case, the Array case and
+nil identically, so a JSON array flows straight through. If the keys it
+reads are the same in both representations, only the *writer* changes:
+stop unwrapping, store the array. Existing rows stay readable, and you
+skip a migration entirely.
+
+Type coercion is usually fine in that second pile too. XML gives you
+strings — `"false"` rather than `false` — and if the reader hands that to
+something like ActiveModel's boolean cast, both the old string and the new
+real boolean land on the same value.
+
+One piece of luck worth knowing about: the two piles tend to fail
+differently. A `dig` that misses returns nil and writes a blank record
+quietly. Code that assumed a Hash, such as `Array#to_h` on what is now a
+list, raises `TypeError` on the first record with data in it. The noisy
+failures are the ones you can trust to find themselves — budget your
+review time for the silent ones.
+
 ## What the client gives you
 
 | Method | Returns | Purpose |

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero-kiwi
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Douglas Greyling