atlas_rb 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d65fea7329731bd0fa0a397a19f5764a05e88397c522baf28721e4a08282e2d3
-  data.tar.gz: 7b2db70c9e1a7d9e8fad5194bcb045baeed562561b1c36a60c174e2c1fc5d0aa
+  metadata.gz: '0947add262eb2b9b4ab993f16c2c379877455e9ece3bca04f41a61bfddf79ee3'
+  data.tar.gz: d239887dfaac21e78a7118503d4ed8ab79b12b3aa174ee18f5a8f31f253ca866
 SHA512:
-  metadata.gz: 335c7d4bd02d6bdb6f297cf86857c042d515680fb8e36991d98a7a7bf4fdd1e52470f0dda4b40605f79d0618c7260a64f2125af2a3100a693c920b51ebc1c1f5
-  data.tar.gz: ce1bc4b16ce482975af0785138574aa6b42fc2cc05ddfee777adbef2834b733bdb93df5390cfc4e9a5012af4b9483cf5676f7213edc8e79afc0fd886d2b84545
+  metadata.gz: b4d59334c7730d11f9f7779b1cbef5c7cef49ce4b1726257a9c8590f258ab4c8aac80ffffa10c1111a38b4d98b95c7b36e824eab925aff4aae1ff87336f7e37e
+  data.tar.gz: a5c0484e6d4204758dc1eee8e2ca6086a289e19e250a404fbdffc4af65eaa7864f2da7f93a9586d4d84776c76b33dbdebb5147ae4d728baed51110864c347e30

data/.version

@@ -1 +1 @@
-1.3.0
+1.3.1

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 1.3.1
+
+### Added — `AtlasRb::Resource.mods_versions` / `mods_version` (MODS version history)
+
+Two bindings for Atlas's MODS version-history endpoints. `mods_versions`
+lists the retained versions of a resource's descriptive metadata;
+`mods_version` fetches the raw MODS XML as of a specific version — together
+enough to drive a line-diff between any two MODS states.
+
+```ruby
+history = AtlasRb::Resource.mods_versions("w-789")
+history["versions"].first["version_id"]  # => "v5"   (newest)
+history["versions"].first["actor_nuid"]   # => "000000002"
+
+old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+```
+
+- `mods_versions` returns the full envelope (`resource_id` + a
+  reverse-chronological `versions` array) as an `AtlasRb::Mash`. Each
+  descriptor mirrors the audit-event shape (`version_id`, `created`,
+  `actor_nuid`, `on_behalf_of_nuid`, `source`, `note`); actor fields are
+  correlated from the audit log and may be `null`. Admin-gated server-side.
+- `mods_version` returns the **raw XML body** (mirroring `Work.mods`). Only
+  XML is version-recoverable — the JSON access copy is overwritten in place
+  — so `kind:` is accepted for parity but XML is the only retained format.
+- Version labels are opaque, sortable OCFL `vN` strings (a Blob's
+  preservation envelope occupies earlier versions, so the first MODS
+  version is typically `v3`). Treat them as identifiers to feed back into
+  `mods_version`, not as ordinals.
+- Both are type-agnostic (Community / Collection / Work) and live on
+  `Resource` beside `history` / `permissions`. A resource with no MODS
+  returns `{ "versions" => [] }`.
+
 ## 1.3.0
 
 ### Added — `AtlasRb::Resource.find_many` (batch resolve by NOID)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.3.0)
+    atlas_rb (1.3.1)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -245,6 +245,44 @@ mode-less session events. Atlas stamps `occurred_at` server-side.
 Authorization errors (`401` / `403`) surface as raw Faraday responses,
 matching `Resource.history`.
 
+### MODS version history
+
+Every descriptive-metadata edit retains the prior MODS XML on the server.
+`Resource.mods_versions` lists the retained versions; `Resource.mods_version`
+fetches the raw MODS XML as of one of them — together enough to render a
+line-diff between any two MODS states. Both are type-agnostic (pass any
+Community, Collection, or Work ID).
+
+```ruby
+history = AtlasRb::Resource.mods_versions("w-789")
+history["resource_id"]                    # => "w-789"
+history["versions"].first["version_id"]   # => "v5"  (newest first)
+history["versions"].first["actor_nuid"]    # => "000000002" (or nil)
+
+# Fetch two versions and diff them:
+old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+```
+
+`mods_versions` returns the full envelope (`resource_id` + a
+reverse-chronological `versions` array) as an `AtlasRb::Mash`; each
+descriptor mirrors the audit-event shape (`version_id`, `created`,
+`actor_nuid`, `on_behalf_of_nuid`, `source`, `note`), so the two streams
+render with the same helpers. Actor attribution is correlated from the
+audit log and may be `null`. The endpoint is admin-gated server-side
+(it exposes edit attribution).
+
+`mods_version` returns the **raw XML body** — like `Work.mods`, not a Mash.
+Only XML is version-recoverable (the JSON access copy is overwritten in
+place), so the server serves historical XML; `kind:` is accepted for parity
+with `Work.mods` but XML is the only retained format.
+
+Version labels are **opaque, sortable OCFL `vN` strings**, not a 1-based
+counter — a Blob's preservation envelope occupies earlier versions, so the
+first MODS version is typically `v3`. Treat them as identifiers to feed back
+into `mods_version`. A resource with no MODS returns `{ "versions" => [] }`;
+`401` / `403` surface as raw Faraday responses, matching `Resource.history`.
+
 ### Re-parenting
 
 `reparent` moves a resource to a new structural parent, binding Atlas's

data/lib/atlas_rb/resource.rb

@@ -166,5 +166,81 @@ module AtlasRb
           .get('/resources/' + id + '/history')&.body
       ))
     end
+
+    # List the retained MODS versions for a resource.
+    #
+    # Wraps Atlas's `GET /resources/<id>/mods/versions`, which returns the
+    # full envelope — `resource_id` plus a reverse-chronological `versions`
+    # array — as an `AtlasRb::Mash`. Each version descriptor mirrors the
+    # audit-event shape (`version_id`, `created`, `actor_nuid`,
+    # `on_behalf_of_nuid`, `source`, `note`) so the two streams render with
+    # the same helpers; actor fields are correlated from the audit log and
+    # may be `null` when a version has no matching edit event.
+    #
+    # Type-agnostic: pass any Modsable resource ID (Community, Collection,
+    # Work). A resource with no MODS comes back as `{ "versions" => [] }`.
+    #
+    # Version labels are opaque, sortable OCFL `vN` strings — not a 1-based
+    # counter — so treat them as identifiers to feed back into
+    # {mods_version}, not as ordinals. The server admin-gates this endpoint
+    # (it exposes edit attribution); `401` / `403` surface as raw Faraday
+    # responses, matching {history}.
+    #
+    # @param id [String] an Atlas resource ID.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
+    # @return [AtlasRb::Mash] the parsed envelope, with `"resource_id"` and a
+    #   `"versions"` array (reverse chronological; possibly empty).
+    #
+    # @example
+    #   history = AtlasRb::Resource.mods_versions("w-789")
+    #   history["versions"].first["version_id"] # => "v5"
+    #   history["versions"].first["actor_nuid"]  # => "000000002"
+    def self.mods_versions(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .get('/resources/' + id + '/mods/versions')&.body
+      ))
+    end
+
+    # Fetch the MODS document as of a specific version.
+    #
+    # Wraps Atlas's `GET /resources/<id>/mods/versions/<version_id>` and
+    # returns the **raw response body** (not parsed) — mirroring
+    # {Work.mods}. Pass a `version_id` obtained from {mods_versions} (an
+    # opaque OCFL `vN` label).
+    #
+    # Only XML is version-recoverable: the JSON access copy is overwritten in
+    # place, so the server serves historical XML (the default). `kind:` is
+    # accepted for parity with {Work.mods} but XML is currently the only
+    # supported format. An unknown version yields a `404` (raw Faraday
+    # response).
+    #
+    # @param id [String] an Atlas resource ID.
+    # @param version_id [String] an OCFL version label from {mods_versions},
+    #   e.g. `"v3"`.
+    # @param kind [String, nil] response format extension. Omit (or pass
+    #   `"xml"`) for the historical XML — the only format the server retains.
+    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
+    #   `User:` header. Required for cerberus-token requests; legacy bearer
+    #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
+    # @return [String] the raw MODS XML body for that version.
+    #
+    # @example Diff two MODS versions
+    #   old_xml = AtlasRb::Resource.mods_version("w-789", "v3")
+    #   new_xml = AtlasRb::Resource.mods_version("w-789", "v5")
+    def self.mods_version(id, version_id, kind: nil, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).get(
+        '/resources/' + id + '/mods/versions/' + version_id +
+          (kind.present? ? ".#{kind}" : '')
+      )&.body
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday