atlas_rb 1.2.2 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29da2e41c70d17572c6c24002ba0ff25beb2ad6cdd940dee157a83133c86efaf
-  data.tar.gz: 9e16fed8e22867c37647a12de104135d78f57995ba5e6decd4929ac6a402bae7
+  metadata.gz: '0947add262eb2b9b4ab993f16c2c379877455e9ece3bca04f41a61bfddf79ee3'
+  data.tar.gz: d239887dfaac21e78a7118503d4ed8ab79b12b3aa174ee18f5a8f31f253ca866
 SHA512:
-  metadata.gz: 7ba5a0216a5cc5dacce4f6822078eb07d71aa4e14b31142c83dd823c0ec177efa92e1712eac0b235c125870611dcd4633817066c5ee70a98d6f85adbec614a7f
-  data.tar.gz: b176fc377d6d802e356c5f0a0fd487c6c899d4b5e323e3017eb773fd11e06dd8ebb415329a4c4e81aef5f55f0086602fc33a6cb82c4699709e0a3209c542a48d
+  metadata.gz: b4d59334c7730d11f9f7779b1cbef5c7cef49ce4b1726257a9c8590f258ab4c8aac80ffffa10c1111a38b4d98b95c7b36e824eab925aff4aae1ff87336f7e37e
+  data.tar.gz: a5c0484e6d4204758dc1eee8e2ca6086a289e19e250a404fbdffc4af65eaa7864f2da7f93a9586d4d84776c76b33dbdebb5147ae4d728baed51110864c347e30

data/.version

@@ -1 +1 @@
-1.2.2
+1.3.1

data/CHANGELOG.md

@@ -1,6 +1,67 @@
 # Changelog
 
-## Unreleased
+## 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)
+
+A binding for Atlas's `POST /resources/find_many`. Resolves a set of NOIDs
+to lightweight digests in **one** round-trip, replacing the `find`-per-id
+fan-out that several Cerberus surfaces (breadcrumbs, linked-member lists,
+load-destination pickers) paid on every render.
+
+```ruby
+nodes   = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+by_noid = nodes.index_by { |n| n["noid"] }
+by_noid["col-456"].title   # => "Some Collection"
+```
+
+- Each digest is `{ "id", "noid", "klass", "title", "thumbnail",
+  "tombstoned" }` — not the full typed payload. `title` / `thumbnail` are
+  `null` for resources off the Modsable backbone (FileSet/Blob).
+- The ids ride in the request **body**, so the list isn't bounded by URL
+  length. Returns one `AtlasRb::Mash` per resolved resource.
+- The result is **unordered** and **may be shorter than the input**:
+  unresolvable ids are dropped, tombstoned ones come back flagged
+  (`"tombstoned" => true`). Index by `"noid"` — don't assume positional
+  correspondence with the input.
+- Resolves NOIDs (alternate ids) only; raw Valkyrie ids are not a supported
+  input.
+
+## 1.2.2
 
 ### Added — `AtlasRb::AuditEvent.emit` (session-scoped audit events)
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.2.2)
+    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
@@ -312,6 +350,27 @@ The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
 
+### Batch resolve (`Resource.find_many`)
+
+When you have a *set* of NOIDs and only need each one's title / klass /
+thumbnail — breadcrumb chains, linked-member lists, load-destination
+pickers — resolve them in one round-trip instead of a `find`-per-id
+fan-out:
+
+```ruby
+nodes   = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+by_noid = nodes.index_by { |n| n["noid"] }
+by_noid["col-456"].title   # => "Some Collection"
+```
+
+Each entry is a lightweight digest — `{ "id", "noid", "klass", "title",
+"thumbnail", "tombstoned" }` — not the full typed payload. The ids travel
+in the request body (no URL-length ceiling). The result is **unordered**
+and **may be shorter than the input**: unresolvable ids are dropped and
+tombstoned resources come back flagged (`"tombstoned" => true`), so index
+by `"noid"` rather than assuming positional correspondence. NOIDs only —
+raw Valkyrie ids are not a supported input.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/resource.rb

@@ -47,6 +47,44 @@ module AtlasRb
                         "resource" => result.first[1])
     end
 
+    # Resolve many resources by NOID in a single round-trip.
+    #
+    # Wraps Atlas's `POST /resources/find_many`, which returns one lightweight
+    # digest per resolvable resource — `{ "id", "noid", "klass", "title",
+    # "thumbnail", "tombstoned" }` — rather than full typed payloads. Use it
+    # anywhere a set of ids would otherwise be resolved with a `find`-per-id
+    # fan-out (breadcrumb chains, linked-member lists, load-destination
+    # pickers): one HTTP call instead of N.
+    #
+    # The ids travel in the request **body**, so the list is not bounded by
+    # URL length. The result is **unordered** and **may be shorter than the
+    # input** — unresolvable ids are dropped silently, and tombstoned
+    # resources come back flagged (`"tombstoned" => true`) rather than
+    # omitted. Index the result by `"noid"`; do not assume positional
+    # correspondence with `ids`.
+    #
+    # @param ids [Array<String>] resource NOIDs to resolve. (Raw Valkyrie ids
+    #   are not a supported input — the endpoint resolves alternate ids only.)
+    # @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 [Array<AtlasRb::Mash>] one digest Mash per resolved resource
+    #   (dot- or string-keyed access); empty when nothing resolved.
+    #
+    # @example Resolve a set of collection titles in one call
+    #   nodes  = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+    #   by_noid = nodes.index_by { |n| n["noid"] }
+    #   by_noid["col-456"].title   # => "Some Collection"
+    def self.find_many(ids, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post('/resources/find_many', JSON.dump(ids: Array(ids)))&.body
+      ).map { |node| AtlasRb::Mash.new(node) }
+    end
+
     # Validate a MODS XML document against Atlas's schema *without* persisting it.
     #
     # Useful for surfacing validation errors in UIs before the user commits.
@@ -128,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.2.2
+  version: 1.3.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday